Merge branch 'ros2:rolling' into triaging-reporting-an-issue

Author: keithkirkwood-3di

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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

source/Tutorials/Beginner-Client-Libraries/Colcon-Tutorial.rst

@@ -37,12 +37,18 @@ Install colcon
 
 .. tabs::
 
-  .. group-tab:: Linux
+  .. group-tab:: Ubuntu
 
     .. code-block:: console
 
         $ sudo apt install python3-colcon-common-extensions
 
+  .. group-tab:: RHEL
+
+    .. code-block:: console
+
+        $ sudo dnf install python3-colcon-common-extensions
+
   .. group-tab:: macOS
 
     .. code-block:: console

source/Tutorials/Intermediate/Rosdep.rst

@@ -157,9 +157,19 @@ If you are using ``rosdep`` with ROS, it is conveniently packaged along with the
 This is the recommended way to get ``rosdep``.
 You can install it with:
 
-.. code-block:: console
+.. tabs::
+
+  .. group-tab:: Ubuntu
+
+    .. code-block:: console
+
+        $ sudo apt install python3-rosdep
+
+  .. group-tab:: RHEL
+
+    .. code-block:: console
 
-    $ apt-get install python3-rosdep
+        $ sudo dnf install python3-rosdep
 
 .. note::
 

source/Tutorials/Intermediate/Tf2/Using-Stamped-Datatypes-With-Tf2-Ros-MessageFilter.rst

@@ -42,12 +42,18 @@ This tutorial expects you to have ``turtle_tf2_py`` package installed.
 
 .. tabs::
 
-  .. group-tab:: Linux
+  .. group-tab:: Ubuntu
 
     .. code-block:: console
 
         $ sudo apt install ros-{DISTRO}-turtle-tf2-py
 
+  .. group-tab:: RHEL
+
+    .. code-block:: console
+
+        $ sudo dnf install ros-{DISTRO}-turtle-tf2-py
+
   .. group-tab:: From Source
 
     .. code-block:: console