Add docs build options and theme requirements (#818)

docs/Makefile

@@ -3,16 +3,42 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
+SOURCES       =
 BUILDDIR      = _build
+PYTHON       = python3
+VENVDIR      = ./venv
+SPHINXBUILD  = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
+
+ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES)
+
+.PHONY: help clean build html text venv Makefile
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+clean:
+	-rm -rf build/* $(VENVDIR)/*
+
+build:
+	-mkdir -p build
+	$(SPHINXBUILD) $(ALLSPHINXOPTS)
+	@echo
+
+html: BUILDER = html
+html: build
+	@echo "Build finished. The HTML pages are in build/html."
+
+text: BUILDER = text
+text: build
+	@echo "Build finished; the text files are in build/text."
+
+venv:
+	$(PYTHON) -m venv $(VENVDIR)
+	$(VENVDIR)/bin/python3 -m pip install -U pip setuptools
+	$(VENVDIR)/bin/python3 -m pip install -r requirements.txt
+	@echo "The venv has been created in the $(VENVDIR) directory"
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/README.rst

@@ -0,0 +1,44 @@
+Python Typing Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Building the docs
+=================
+
+The documentation is built with tools which are not included in this
+tree but are maintained separately and are available from
+`PyPI <https://pypi.org/>`_.
+
+* `Sphinx <https://pypi.org/project/Sphinx/>`_
+* `python-docs-theme <https://pypi.org/project/python-docs-theme/>`_
+
+The easiest way to install these tools is to create a virtual environment and
+install the tools into there.
+
+Using make
+----------
+
+To get started on UNIX, you can create a virtual environment with the command ::
+
+  make venv
+
+That will install all the tools necessary to build the documentation. Assuming
+the virtual environment was created in the ``venv`` directory (the default;
+configurable with the VENVDIR variable), you can run the following command to
+build the HTML output files::
+
+  make html
+
+By default, if the virtual environment is not created, the Makefile will
+look for instances of sphinxbuild and blurb installed on your process PATH
+(configurable with the SPHINXBUILD and BLURB variables).
+
+Available make targets are:
+
+* "clean", which removes all build files.
+
+* "venv", which creates a virtual environment with all necessary tools
+  installed.
+
+* "html", which builds standalone HTML files for offline viewing.
+
+* "text", which builds a plain text file for each source file.

docs/conf.py

@@ -44,7 +44,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'python_docs_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/requirements.txt

@@ -0,0 +1,10 @@
+# Requirements to build the Python documentation
+
+# Sphinx version is pinned so that new versions that introduce new warnings
+# won't suddenly cause build failures. Updating the version is fine as long
+# as no warnings are raised by doing so.
+sphinx==3.2.1
+
+# The theme used by the documentation is stored separately, so we need
+# to install that as well.
+python-docs-theme