Add sphinx-autobuild and corresponding task

.github/workflows/lint-test.yml

@@ -49,7 +49,7 @@ jobs:
         run: invoke benchmark
 
       - name: sphinx build 🐪
-        run: invoke doc
+        run: invoke docbuild
 
       - name: check-manifest 📰
         run: check-manifest

.github/workflows/release.yml

@@ -25,7 +25,7 @@ jobs:
           pip install .[dev] build twine
 
       - name: Build documentation with Sphinx 🐪
-        run: invoke doc
+        run: invoke docbuild
 
       - name: Deploy documentation 🚀
         uses: JamesIves/[email protected]

CONTRIBUTING.md

@@ -79,10 +79,14 @@ The relevant files are in `docs/`:
 - `index.md`: Landing documentation page. It includes the `README.md`.
 - `reference.md`: Generates API documentation for `content` and `encoders` modules using [sphinx.ext.autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html).
 
-The documentation can be build locally using
+To build the documentation in development, with live reload at http://127.0.0.1:8000/, run:
 
 ```
 invoke doc
 ```
 
-The HTML pages will be generated in `_build`.
+To build the documentation once into the `_build` folder, run:
+
+```
+invoke docbuild
+```

setup.cfg

@@ -55,6 +55,7 @@ dev =
 	pytest-tornado
 	sphinx
 	sphinx-argparse
+	sphinx-autobuild
 	h5grove[tornado]
 	types-contextvars
 	types-dataclasses

tasks.py

@@ -43,8 +43,16 @@ def test(c, verbose=False, keyword="", cov_lines=False):
 
 
 @task
-def doc(c):
+def docbuild(c):
     """Sphinx build"""
     result = c.run(f"{sys.executable} -m sphinx -W -b html docs _build")
     if result.exited != 0:
         raise SystemExit(result.exited)
+
+
+@task
+def doc(c):
+    """Sphinx autobuild"""
+    result = c.run(f"{sys.executable} -m sphinx_autobuild -W -b html docs _build")
+    if result.exited != 0:
+        raise SystemExit(result.exited)