Add live docs rebuilding using sphinx-autobuild (#916)

Add a new tox target, `livedocs`, that uses sphinx-autobuild to monitor
the docs and auto rebuild the HTML docs when they change.

It also starts a webserver on 127.0.0.1:8000 using livereload to serve
the docs, which will automatically reload the pages in your browser as
they are changed.

Add docs on updating the docs.

Add sphinx-rtd-theme so that the docs generated in development match the
style that they are displayed in on readthedocs.

Co-authored-by: Alan Crosswell <[email protected]>

Author: tevansuk

docs/Makefile

@@ -175,3 +175,6 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -42,6 +42,7 @@
     "sphinx.ext.coverage",
     "rfc",
     "m2r",
+    "sphinx_rtd_theme",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -120,7 +121,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-# html_theme = 'classic'
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -200,11 +201,11 @@
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    #'papersize': 'letterpaper',
+    # 'papersize': 'letterpaper',
     # The font size ('10pt', '11pt' or '12pt').
-    #'pointsize': '10pt',
+    # 'pointsize': '10pt',
     # Additional stuff for the LaTeX preamble.
-    #'preamble': '',
+    # 'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

docs/contributing.rst

@@ -52,6 +52,32 @@ can also (largely) stop worrying about code style, although you should always
 check how the code looks after ``black`` has formatted it, and think if there
 is a better way to structure the code so that it is more readable.
 
+Documentation
+=============
+
+You can edit the documentation by editing files in ``docs/``. This project
+uses sphinx to turn ``ReStructuredText`` into the HTML docs you are reading.
+
+In order to build the docs in to HTML, you can run::
+
+    tox -e docs
+
+This will build the docs, and place the result in ``docs/_build/html``.
+Alternatively, you can run::
+
+    tox -e livedocs
+
+This will run ``sphinx`` in a live reload mode, so any changes that you make to
+the ``RST`` files will be automatically detected and the HTML files rebuilt.
+It will also run a simple HTTP server available at `<http://localhost:8000/>`_
+serving the HTML files, and auto-reload the page when changes are made.
+
+This allows you to edit the docs and see your changes instantly reflected in
+the browser.
+
+* `ReStructuredText primer
+  <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
+
 Pull requests
 =============
 

tox.ini

@@ -46,15 +46,19 @@ passenv =
 ignore_errors = true
 ignore_outcome = true
 
-[testenv:docs]
+[testenv:{docs,livedocs}]
 basepython = python3.8
 changedir = docs
 whitelist_externals = make
-commands = make html
+commands =
+    docs: make html
+    livedocs: make livehtml
 deps =
     sphinx<3
     oauthlib>=3.1.0
     m2r>=0.2.1
+    sphinx-rtd-theme
+    livedocs: sphinx-autobuild
 
 [testenv:flake8]
 basepython = python3.8