docs: Use sphinx-autobuild to streamline documentation (#339)

See also: https://github.com/executablebooks/sphinx-autobuild

Author: tony

Makefile

@@ -26,14 +26,8 @@ watch_test:
 build_docs:
 	$(MAKE) -C docs html
 
-watch_docs:
-	if command -v entr > /dev/null; then ${DOC_FILES} | entr -c $(MAKE) build_docs; else $(MAKE) build_docs entr_warn; fi
-
-serve_docs:
-	$(MAKE) -C docs serve
-
-dev_docs:
-	$(MAKE) -j watch_docs serve_docs
+start_docs:
+	$(MAKE) -C docs start
 
 flake8:
 	flake8 libvcs tests

docs/Makefile

@@ -175,3 +175,6 @@ serve_py3:
 
 dev:
 	$(MAKE) -j watch serve
+
+start:
+	poetry run sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/developing.md

@@ -19,6 +19,15 @@ Rerun tests on file change: `make watch_test` (requires [entr(1)])
 
 ## Documentation
 
+[sphinx-autobuild] will automatically build the docs, watch for file changes and launch a server.
+
+From home directory: `make start_docs`
+From inside `docs/`: `make start`
+
+[sphinx-autobuild]: https://github.com/executablebooks/sphinx-autobuild
+
+### Manual documentation (the hard way)
+
 Default preview server: http://localhost:8022
 
 `cd docs/` and `make html` to build. `make serve` to start http server.

poetry.lock

@@ -54,6 +54,7 @@ alagitpull = "^0.1.0"
 sphinx-issues = "^3.0.0"
 sphinx-click = "*"
 sphinx-autodoc-typehints = "~1.17.0"
+sphinx-autobuild = "^2021.3.14"
 myst_parser = "~0.17.0"
 
 ### Testing ###
@@ -73,7 +74,7 @@ isort = "*"
 flake8 = "*"
 
 [tool.poetry.extras]
-docs = ["sphinx", "sphinx-issues", "sphinx-click", "sphinx-autodoc-typehints", "myst_parser", "alagitpull"]
+docs = ["sphinx", "sphinx-issues", "sphinx-click", "sphinx-autodoc-typehints", "myst_parser", "sphinx-autobuild", "alagitpull"]
 test = ["pytest", "pytest-rerunfailures"]
 coverage = ["codecov", "coverage", "pytest-cov"]
 format = ["black", "isort"]