Merge branch 'rolling' into 3di-toc-changes

Author: dmarshant

Makefile

@@ -9,6 +9,8 @@ ifeq ($(OS),Windows_NT)
 endif
 BUILD      = $(PYTHON) -m sphinx
 OPTS       =-c . -W # Treat warnings as errors
+LIVE_HOST  ?= 0.0.0.0
+LIVE_PORT  ?= 2022
 
 DICTIONARIES := codespell_dictionary.txt codespell_whitelist.txt
 
@@ -61,4 +63,7 @@ linkcheck:
 	@echo
 	@echo "Check finished. Report is in $(LINKCHECKDIR)."
 
-.PHONY: help Makefile multiversion test test-tools linkcheck lint spellcheck check-dictionaries sort-dictionaries
+serve:
+	sphinx-autobuild --host $(LIVE_HOST) --port $(LIVE_PORT) -c . $(SOURCE) $(OUT)/html
+
+.PHONY: help Makefile multiversion test test-tools linkcheck serve lint spellcheck check-dictionaries sort-dictionaries

README.md

@@ -51,6 +51,27 @@ For local testing of the current tree use:
 
 `sensible-browser build/html/index.html`
 
+### Live-reload local development
+
+To iterate on documentation without manually rebuilding and refreshing the browser, use [`sphinx-autobuild`](https://github.com/sphinx-doc/sphinx-autobuild).
+It watches the source files, rebuilds incrementally on save, and serves the result with automatic browser reload.
+
+`sphinx-autobuild` is installed as part of `requirements.txt`.
+Start the live server with:
+
+```
+make serve
+```
+
+Then open `http://localhost:2022` in a browser.
+
+The `serve` target binds to `0.0.0.0:2022` by default (a little ROS 2 vibe) so the server is reachable through devcontainer / port forwarding.
+Override the bind address or port if needed:
+
+```
+make serve LIVE_HOST=127.0.0.1 LIVE_PORT=8080
+```
+
 ### Spelling Check
 
 To check the spelling, use:

requirements.txt

@@ -4,6 +4,7 @@ docutils
 pip
 pytest
 sphinx
+sphinx-autobuild
 sphinx-copybutton
 sphinx-lint
 sphinx-multiversion