Add sphinx autobuild

Author: coretl

docs/conf.py

@@ -24,7 +24,6 @@
     git_branch = check_output("git branch --show-current".split(), cwd=root)
     version = git_branch.decode().strip()
 else:
-    branch = "main"
     version = release
 
 extensions = [

docs/developer/how-to/build-docs.rst

@@ -17,4 +17,22 @@ locally with a web browse::
 
     $ firefox build/html/index.html
 
+Autobuild
+---------
+
+You can also run an autobuild process, which will watch your ``docs``
+directory for changes and rebuild whenever it sees changes, reloading any
+browsers watching the pages::
+
+    $ tox -e docs autobuild
+
+You can view the pages at localhost::
+
+    $ firefox http://localhost:8000
+
+If you are making changes to source code too, you can tell it to watch
+changes in this directory too::
+
+    $ tox -e docs autobuild -- --watch src
+
 .. _sphinx: https://www.sphinx-doc.org/

setup.cfg

@@ -41,6 +41,7 @@ dev =
     pydata-sphinx-theme < 0.10.1
     pytest-cov
     setuptools_scm[toml]>=6.2
+    sphinx-autobuild
     sphinx-copybutton
     sphinx-design
     tox
@@ -122,5 +123,5 @@ allowlist_externals = pre-commit
 commands = pre-commit run --all-files {posargs}
 
 [testenv:docs]
-allowlist_externals = sphinx-build
-commands = sphinx-build -EWT --keep-going docs build/html {posargs}
+allowlist_externals = sphinx-build sphinx-autobuild
+commands = sphinx-{posargs:build -EW --keep-going} -T docs build/html