diff --git a/Makefile b/Makefile index 4c833e0a60..aebff051af 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 7c613ccbf1..33beec6db1 100644 --- a/README.md +++ b/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: diff --git a/requirements.txt b/requirements.txt index f952c4882f..f938445a0b 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,6 +4,7 @@ docutils pip pytest sphinx +sphinx-autobuild sphinx-copybutton sphinx-lint sphinx-multiversion diff --git a/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst b/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst index 8879e4c92c..0a1f829c38 100644 --- a/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst +++ b/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 `__ 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^