Update docs reference and improve makefile (#56)

.github/workflows/ci.yml

@@ -89,4 +89,4 @@ jobs:
       - name: Build Docs
         run: |
           cd docs
-          pipenv run make html
+          pipenv run make html SPHINXOPTS="-W --keep-going"

docs/Makefile

@@ -14,6 +14,9 @@ help:
 
 .PHONY: help Makefile
 
+cleanall: clean
+	@rm source/reference/*
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

docs/make.bat

@@ -25,11 +25,21 @@ if errorlevel 9009 (
 
 if "%1" == "" goto help
 
+if "%1" == "cleanall" goto cleanall
+
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
+:cleanall
+REM This is untested, please fix if broken
+%SPHINXBUILD% -M clean %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+cd %SOURCEDIR%
+cd reference
+del .*.
+goto end
+
 :end
 popd

docs/source/contributing/docs.rst

@@ -62,4 +62,9 @@ For example,
 Tips and Tricks
 ~~~~~~~~~~~~~~~
 Sometimes Sphinx will do some weird stuff and things will stop working nicely.
-In this case, a simple ``make clean`` (or ``make.bat clean`` for Windows) should do the trick.
+In this case, a simple ``make cleanall`` (or ``make.bat cleanall`` for Windows) should do the trick.
+
+.. warning::
+
+   ``make.bat cleanall`` is _untested_ on Windows, be careful when using it. You can alternatively
+   use ``make.bat clean`` and remove the contents of ``docs/source/reference``.

docs/source/index.rst

@@ -24,4 +24,4 @@ Explore some of the technical documentation we have at our disposal!
   contributing
   reference_index
   developers
-  deploying
+  production