Add docs for building the docs locally

This adds documentation for how to build the docs locally.

Previously the `make docs` command required you to have Python 3 and tox
installed system-wide, neither of which are required for any of our
other projects anymore, and this wasn't documented anywhere.

This PR changes `make docs` to use pyenv to install Python 3 and tox, as
all our other Python projects do, and adds a Building the Docs Locally
page to the docs with instructions on how to install pyenv and build the
docs locally.

pyenv and tox are _not_ added to the general client dev install
instructions since they're only needed to build the docs.

.python-version

+3.6.9

Makefile

@@ -36,12 +36,12 @@ lint: node_modules/.uptodate
 	yarn run lint
 
 .PHONY: docs
-docs:
-	tox -e py3-docs
+docs: python
+	tox -e py36-docs
 
 .PHONY: checkdocs
-checkdocs:
-	tox -e py3-checkdocs
+checkdocs: python
+	tox -e py36-checkdocs
 
 .PHONY: clean
 clean:
@@ -56,6 +56,10 @@ format:
 checkformatting:
 	yarn run checkformatting
 
+.PHONY: python
+python:
+	@./bin/install-python
+
 build/manifest.json: node_modules/.uptodate
 	yarn run build
 

bin/install-python

+#!/usr/bin/env sh
+#
+# Install each required version of Python (from the .python-version file),
+# if it's not installed already.
+#
+# Also install tox in each pyenv copy of Python, if not installed already.
+#
+# Requirements
+# ============
+#
+# * pyenv (https://github.com/pyenv/pyenv) to install versions of Python.
+#
+# Usage
+# =====
+#
+# $ ./bin/install-python
+
+# Exit if we're running on Travis CI.
+# On Travis we just want to use the versions of Python provided in the Travis
+# VM, even though they may not have be the same patch versions as in
+# .python-version.
+if [ "$TRAVIS" = "true" ]
+then
+  exit
+fi
+
+# Exit if we're running on Jenkins.
+# On Jenkins we run the tests in Docker and we just want to use the versions of
+# Python provided in the Docker container.
+if [ -n "${JENKINS_URL+set}" ]; then
+  exit
+fi
+
+# Loop over every $python_version in the .python-version file.
+while IFS= read -r python_version
+do
+    # Install this version of Python in pyenv if it's not installed already.
+    pyenv install --skip-existing "$python_version"
+
+    # Install tox in this version of Python if it's not already installed.
+    if ! "$(pyenv root)/versions/$python_version/bin/tox" --version > /dev/null 2>&1
+    then
+        "$(pyenv root)/versions/$python_version/bin/pip" install --quiet --disable-pip-version-check tox > /dev/null
+    fi
+done < .python-version

docs/developers/docs.rst

+Building the Docs Locally
+=========================
+
+The Hypothesis client's documentation is hosted at https://h.readthedocs.io/projects/client/.
+The docs are built using https://readthedocs.org.
+This page will show you how to build the docs locally, so you can preview
+changes to the documentation locally before sending a pull request.
+
+You Will Need
+-------------
+
+* `Git <https://git-scm.com/>`_
+
+* `pyenv <https://github.com/pyenv/pyenv>`_
+
+  Follow the instructions in the pyenv README to install it.
+  The Homebrew method works best on macOS.
+
+Clone the Git Repo
+------------------
+
+If you haven't already, use ``git clone`` to make a local copy of the client
+repo::
+
+    git clone https://github.com/hypothesis/client.git
+
+This will download the code into a ``client`` directory in your current working
+directory. You need to be in the ``client`` directory for the remainder of the
+installation process::
+
+    cd client
+
+Build the Docs
+--------------
+
+::
+
+    make docs
+
+This will build the docs and serve them locally on port 8000.
+Open http://localhost:8000/ to preview the docs.
+When you make changes to the files in the ``docs/`` folder the preview will
+update automatically.
+
+The first time you run ``make docs`` it might take a while to start because it
+might need to install Python, and it'll need to create a Python virtualenv and
+install the Python packages needed to build the docs into it.

docs/developers/index.rst

@@ -11,4 +11,5 @@ the Hypothesis client.
    envvars
    mobile
    security
+   docs
    arch/index