add make target "serve" to start the live html server. (backport #6876)

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

source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst

@@ -96,6 +96,27 @@ This is the recommended way to test out local changes.
 The build process can take some time.
 To see the output, open ``build/html/index.html`` in your browser.
 
+Live-reload local development
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When iterating on documentation, instead of re-running ``make html`` and refreshing the browser after every edit, use `sphinx-autobuild <https://github.com/sphinx-doc/sphinx-autobuild>`__ to watch the source files, rebuild incrementally on save, and serve the result with automatic browser reload.
+
+``sphinx-autobuild`` is installed as part of ``requirements.txt``.
+Start the live server with:
+
+.. code-block:: console
+
+   $ make serve
+
+Then open ``http://localhost:8000`` in a browser.
+
+The ``serve`` target binds to ``0.0.0.0:8000`` by default so the server is reachable through devcontainer / port forwarding.
+Override the bind address or port if needed:
+
+.. code-block:: console
+
+   $ make serve LIVE_HOST=127.0.0.1 LIVE_PORT=8080
+
 
 Checking / Testing the site
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^