From 253db9e837118c9e93fb83d1b03f55d5248cb518 Mon Sep 17 00:00:00 2001
From: Sean Hammond <git@snhmnd.fastmail.com>
Date: Tue, 3 Sep 2019 11:12:05 +0100
Subject: [PATCH] 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           |  1 +
 Makefile                  | 12 ++++++----
 bin/install-python        | 45 +++++++++++++++++++++++++++++++++++++
 docs/developers/docs.rst  | 47 +++++++++++++++++++++++++++++++++++++++
 docs/developers/index.rst |  1 +
 5 files changed, 102 insertions(+), 4 deletions(-)
 create mode 100644 .python-version
 create mode 100755 bin/install-python
 create mode 100644 docs/developers/docs.rst

diff --git a/.python-version b/.python-version
new file mode 100644
index 00000000000..cff2619cfb9
--- /dev/null
+++ b/.python-version
@@ -0,0 +1 @@
+3.6.9
diff --git a/Makefile b/Makefile
index 9d7c4d6f3ea..c5cae883704 100644
--- a/Makefile
+++ b/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
 
diff --git a/bin/install-python b/bin/install-python
new file mode 100755
index 00000000000..09c74ac1443
--- /dev/null
+++ b/bin/install-python
@@ -0,0 +1,45 @@
+#!/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
diff --git a/docs/developers/docs.rst b/docs/developers/docs.rst
new file mode 100644
index 00000000000..259c9187c9b
--- /dev/null
+++ b/docs/developers/docs.rst
@@ -0,0 +1,47 @@
+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.
diff --git a/docs/developers/index.rst b/docs/developers/index.rst
index 40d64e14ba6..f9f0a1f0470 100644
--- a/docs/developers/index.rst
+++ b/docs/developers/index.rst
@@ -11,4 +11,5 @@ the Hypothesis client.
    envvars
    mobile
    security
+   docs
    arch/index