Contributing documentation, closes #292

docs/contributing.rst

@@ -0,0 +1,67 @@
+.. _contributing:
+
+==============
+ Contributing
+==============
+
+To work on this library locally, first checkout the code. Then create a new virtual environment::
+
+    git clone git@github.com:simonw/sqlite-utils
+    cd sqlite-utils
+    python3 -mvenv venv
+    source venv/bin/activate
+
+Or if you are using ``pipenv``::
+
+    pipenv shell
+
+Within the virtual environment running ``sqlite-utils`` should run your locally editable version of the tool. You can use ``which sqlite-utils`` to confirm that you are running the version that lives in your virtual environment.
+
+.. _contributing_tests:
+
+Running the tests
+=================
+
+To install the dependencies and test dependencies::
+
+    pip install -e '.[test]'
+
+To run the tests::
+
+    pytest
+
+.. _contributing_docs:
+
+Building the documentation
+==========================
+
+To build the documentation, first install the documentation dependencies::
+
+    pip install -e '.[docs]'
+
+Then run ``make livehtml`` from the ``docs/`` directory to start a server on port 8000 that will serve the documentation and live-reload any time you make an edit to a ``.rst`` file::
+
+    cd docs
+    make livehtml
+
+.. _contributing_linting:
+
+Linting and formatting
+======================
+
+``sqlite-utils`` uses `Black <https://black.readthedocs.io/>`__ for code formatting, and `flake8 <https://flake8.pycqa.org/>`__ and `mypy <https://mypy.readthedocs.io/>`__ for linting and type checking.
+
+Black is installed as part of ``pip install -e '.[test]'`` - you can then format your code by running it in the root of the project::
+
+    black .
+
+To install ``mypy`` and ``flake8`` run the following::
+
+    pip install -e '.[flake8,mypy]'
+
+Both commands can then be run in the root of the project like this::
+
+    flake8
+    mypy sqlite_utils
+
+All three of these tools are run by our CI mechanism against every commit and pull request.

docs/index.rst

@@ -32,6 +32,7 @@ Contents
    installation
    cli
    python-api
+   contributing
    changelog
 
 Take a look at `this script <https://github.com/simonw/russian-ira-facebook-ads-datasette/blob/master/fetch_and_build_russian_ads.py>`_ for an example of this library in action.