Add sphinx-autobuild and new recipe for it in make files

Author: Jackenmen

Makefile

@@ -15,8 +15,9 @@ help: ensurevenv
 	@echo "  bumpdeps    to bump dependencies in requirement files."
 	@echo "  compiledeps to update requirements.txt files to adhere to dependencies"
 	@echo "              declared in requirements.in files (with minimal version changes)."
+	@echo "  livehtml    to serve dirhtml documentation locally and auto-build on changes."
 
-.PHONY: help bumpdeps compiledeps ensurevenv Makefile
+.PHONY: help bumpdeps compiledeps ensurevenv livehtml Makefile
 
 # Note to whoever sees this in future:
 # Using indentation before `ensurevenv` lines breaks this target
@@ -61,6 +62,9 @@ aftercompiledeps:
 	@echo
 	$(MAKE) ensurevenv
 
+livehtml: ensurevenv
+	./venv/bin/sphinx-autobuild -b dirhtml -d "$(BUILDDIR)/doctrees" "$(SOURCEDIR)" "$(BUILDDIR)/dirhtml" $(SPHINXOPTS) $(O)
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile ensurevenv

dev-requirements.in

@@ -4,3 +4,4 @@ flake8
 isort
 pip-tools
 pre-commit
+sphinx-autobuild

dev-requirements.txt

@@ -4,14 +4,30 @@
 #
 #    pip-compile dev-requirements.in
 #
+alabaster==0.7.12
+    # via
+    #   -c requirements.txt
+    #   sphinx
 appdirs==1.4.4
     # via
     #   black
     #   virtualenv
+babel==2.9.1
+    # via
+    #   -c requirements.txt
+    #   sphinx
 black==21.6b0
     # via -r dev-requirements.in
+certifi==2021.5.30
+    # via
+    #   -c requirements.txt
+    #   requests
 cfgv==3.3.0
     # via pre-commit
+chardet==4.0.0
+    # via
+    #   -c requirements.txt
+    #   requests
 click==8.0.1
     # via
     #   black
@@ -20,22 +36,50 @@ colorama==0.4.4
     # via
     #   -c requirements.txt
     #   click
+    #   sphinx
+    #   sphinx-autobuild
 distlib==0.3.2
     # via virtualenv
+docutils==0.17.1
+    # via
+    #   -c requirements.txt
+    #   sphinx
 filelock==3.0.12
     # via virtualenv
 flake8==3.9.2
     # via -r dev-requirements.in
 identify==2.2.10
     # via pre-commit
+idna==2.10
+    # via
+    #   -c requirements.txt
+    #   requests
+imagesize==1.2.0
+    # via
+    #   -c requirements.txt
+    #   sphinx
 isort==5.9.1
     # via -r dev-requirements.in
+jinja2==3.0.1
+    # via
+    #   -c requirements.txt
+    #   sphinx
+livereload==2.6.3
+    # via sphinx-autobuild
+markupsafe==2.0.1
+    # via
+    #   -c requirements.txt
+    #   jinja2
 mccabe==0.6.1
     # via flake8
 mypy-extensions==0.4.3
     # via black
 nodeenv==1.6.0
     # via pre-commit
+packaging==21.0
+    # via
+    #   -c requirements.txt
+    #   sphinx
 pathspec==0.8.1
     # via black
 pep517==0.10.0
@@ -48,17 +92,75 @@ pycodestyle==2.7.0
     # via flake8
 pyflakes==2.3.1
     # via flake8
+pygments==2.9.0
+    # via
+    #   -c requirements.txt
+    #   sphinx
+pyparsing==2.4.7
+    # via
+    #   -c requirements.txt
+    #   packaging
+pytz==2021.1
+    # via
+    #   -c requirements.txt
+    #   babel
 pyyaml==5.4.1
     # via pre-commit
 regex==2021.7.6
     # via black
+requests==2.25.1
+    # via
+    #   -c requirements.txt
+    #   sphinx
 six==1.16.0
-    # via virtualenv
+    # via
+    #   livereload
+    #   virtualenv
+snowballstemmer==2.1.0
+    # via
+    #   -c requirements.txt
+    #   sphinx
+sphinx==4.0.3
+    # via
+    #   -c requirements.txt
+    #   sphinx-autobuild
+sphinx-autobuild==2021.3.14
+    # via -r dev-requirements.in
+sphinxcontrib-applehelp==1.0.2
+    # via
+    #   -c requirements.txt
+    #   sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via
+    #   -c requirements.txt
+    #   sphinx
+sphinxcontrib-htmlhelp==2.0.0
+    # via
+    #   -c requirements.txt
+    #   sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via
+    #   -c requirements.txt
+    #   sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via
+    #   -c requirements.txt
+    #   sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via
+    #   -c requirements.txt
+    #   sphinx
 toml==0.10.2
     # via
     #   black
     #   pep517
     #   pre-commit
+tornado==6.1
+    # via livereload
+urllib3==1.26.6
+    # via
+    #   -c requirements.txt
+    #   requests
 virtualenv==20.4.7
     # via pre-commit
 wheel==0.36.2

make.bat

@@ -15,6 +15,7 @@ set BUILDDIR=build
 
 if "%1" == "bumpdeps" goto bumpdeps
 if "%1" == "compiledeps" goto compiledeps
+if "%1" == "livehtml" goto livehtml
 if "%1" == "" goto help
 
 call :ensurevenv
@@ -48,6 +49,7 @@ echo.---
 echo.  bumpdeps    to bump dependencies in requirement files.
 echo.  compiledeps to update requirements.txt files to adhere to dependencies
 echo.              declared in requirements.in files (with minimal version changes).
+echo.  livehtml    to serve dirhtml documentation locally and auto-build on changes.
 goto end
 
 :bumpdeps
@@ -66,6 +68,11 @@ venv\Scripts\pip-compile --quiet dev-requirements.in
 call :aftercompiledeps
 goto end
 
+:livehtml
+call :ensurevenv
+venv\Scripts\sphinx-autobuild -b dirhtml -d %BUILDDIR%\doctrees %SOURCEDIR% %BUILDDIR%\dirhtml %SPHINXOPTS% %O%
+goto end
+
 :aftercompiledeps
 venv\Scripts\pre-commit run mixed-line-ending --files requirements.txt dev-requirements.txt >nul
 git diff -U1 -- requirements.txt dev-requirements.txt