ros2 · christophebedard · Mar 14, 2025 · Mar 13, 2025 · Mar 14, 2025 · Mar 14, 2025
diff --git a/.sphinx_tamer.yaml b/.sphinx_tamer.yaml
@@ -0,0 +1,10 @@
+sentence_scan:
+    extra_patterns:
+    - Steven! Ragnar
+    - ros2.org
+    - nav2.org
+    - ros2.repos
+    - 2.X
+    - (\s|^)(\.)(idl|msg|srv|action|NET|rviz)
+    ignorable_prefixes:
+    - Releases/
diff --git a/Makefile b/Makefile
@@ -23,7 +23,7 @@ multiversion: Makefile
 	@$(BUILD) -M $@ "$(SOURCE)" "$(OUT)" $(OPTS)
 
 lint:
-	sphinx-lint source
+	./sphinx-lint-with-ros source
 
 test:
 	doc8 --ignore D001 --ignore-path build

diff --git a/plugins/ros_checkers.py b/plugins/ros_checkers.py
@@ -0,0 +1,16 @@
+#!/usr/bin/python3
+from sphinxlint.checkers import checker
+import subprocess
+import yaml
+
+
+@checker('.rst', '.md')
+def check_sentence_count(file, lines, options=None):
+    output = subprocess.check_output(['sphinx_sentence_scan_single', '.', file])
+    results = yaml.safe_load(output)
+    for result in results:
+        sentences = result['sentences']
+        for first, second in zip(sentences, sentences[1:]):
+            words0 = ' '.join(first.split()[-3:])  # last three words
+            words1 = ' '.join(second.split()[:3])  # first three words
+            yield result['line_num'], f'Each sentence must start on a new line. Break between "{words0}" and "{words1}"'
diff --git a/requirements.txt b/requirements.txt
@@ -9,3 +9,4 @@ sphinx-multiversion
 sphinx-rtd-theme
 sphinx-tabs
 sphinxcontrib-mermaid
+sphinx-tamer
diff --git a/source/Concepts/Intermediate/About-Executors.rst b/source/Concepts/Intermediate/About-Executors.rst
@@ -202,4 +202,4 @@ Further information
   ROS Industrial Conference.
   Virtual event.
   16 December 2020.
-* Daniel Casini, Tobias Blass, Ingo Lütkebohle, and Björn Brandenburg: `"Response-Time Analysis of ROS 2 Processing Chains under Reservation-Based Scheduling" <https://drops.dagstuhl.de/opus/volltexte/2019/10743/pdf/LIPIcs-ECRTS-2019-6.pdf>`_, Proc. of 31st ECRTS 2019, Stuttgart, Germany, July 2019.
+* Daniel Casini, Tobias Blass, Ingo Lütkebohle, and Björn Brandenburg: `"Response-Time Analysis of ROS 2 Processing Chains under Reservation-Based Scheduling" <https://drops.dagstuhl.de/opus/volltexte/2019/10743/pdf/LIPIcs-ECRTS-2019-6.pdf>`_, Proceedings of 31st ECRTS 2019, Stuttgart, Germany, July 2019.
diff --git a/source/Contact.rst b/source/Contact.rst
@@ -59,7 +59,7 @@ If following a tutorial or online instructions provide a link to the specific in
 
 * Use a descriptive headline or subject line.
   Bad: "rviz doesn't work".
-  Good: "Rviz crashing looking for missing .so after latest apt update"
+  Good: "Rviz crashing looking for missing ``.so`` after latest apt update"
 * Include information about the exact platform, software, versions, and environment relevant to the problem.
   This includes how you installed the software (from binaries or from source) and which ROS middleware/DDS vendor you are using (if you know it).
 * Any warnings or errors.

diff --git a/source/How-To-Guides/Documenting-a-ROS-2-Package.rst b/source/How-To-Guides/Documenting-a-ROS-2-Package.rst
@@ -240,6 +240,6 @@ On each job page, you can see when a build was last triggered, as well as the st
 Further Reading
 ---------------
 
-* ``rosdoc2`` readme: https://github.com/ros-infrastructure/rosdoc2/blob/main/README.md
-* ROS 2 design document on package documentation: https://design.ros2.org/articles/per_package_documentation.html
-* The ROS 2 cookbook: https://github.com/mikeferguson/ros2_cookbook/blob/main/pages/rosdoc2.md
+* `rosdoc2 readme <https://github.com/ros-infrastructure/rosdoc2/blob/main/README.md>`_
+* `ROS 2 design document on package documentation <https://design.ros2.org/articles/per_package_documentation.html>`_
+* `The ROS 2 cookbook <https://github.com/mikeferguson/ros2_cookbook/blob/main/pages/rosdoc2.md>`_
diff --git a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Launch-Files.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Launch-Files.rst
@@ -13,7 +13,7 @@ Migrating Launch Files
    :depth: 1
    :local:
 
-While launch files in ROS 1 are always specified using `.xml <https://wiki.ros.org/roslaunch/XML>`__ files, ROS 2 supports Python scripts to enable more flexibility (see `launch package <https://github.com/ros2/launch/tree/{REPOS_FILE_BRANCH}/launch>`__) as well as XML and YAML files.
+While launch files in ROS 1 are always specified using `xml <https://wiki.ros.org/roslaunch/XML>`__ files, ROS 2 supports Python scripts to enable more flexibility (see `launch package <https://github.com/ros2/launch/tree/{REPOS_FILE_BRANCH}/launch>`__) as well as XML and YAML files.
 
 This guide describes how to write ROS 2 XML launch files for an easy migration from ROS 1.
 

diff --git a/source/How-To-Guides/Releasing/Release-Track.rst b/source/How-To-Guides/Releasing/Release-Track.rst
@@ -112,7 +112,8 @@ Most repositories will be using git, but some legacy repositories might be using
 Version
 ^^^^^^^
 
-This is the version of the package you are releasing. (e.g. ``1.0.3``)
+This is the version of the package you are releasing.
+(e.g. ``1.0.3``)
 
 .. code-block:: bash
 

diff --git a/source/How-To-Guides/Releasing/Releasing-a-Package.rst b/source/How-To-Guides/Releasing/Releasing-a-Package.rst
@@ -20,7 +20,7 @@ Releasing a Package
 **Releasing a package makes your package available on the public ROS 2 buildfarm.**
 This will:
 
-* Make your package available to be installed via package managers (eg. ``apt`` on Ubuntu) for all supported Linux platforms in a ROS distribution as described in `REP 2000 <https://ros.org/reps/rep-2000.html>`_.
+* Make your package available to be installed via package managers (e.g. ``apt`` on Ubuntu) for all supported Linux platforms in a ROS distribution as described in `REP 2000 <https://ros.org/reps/rep-2000.html>`_.
 * Allow your package to have API documentation automatically generated.
 * Make your package part of the `ROS Index <https://index.ros.org>`_.
 * (Optionally) Allow you to have automatic CI run for pull requests in your repository.

diff --git a/source/How-To-Guides/Using-Variants.rst b/source/How-To-Guides/Using-Variants.rst
@@ -1,7 +1,8 @@
 Using variants
 ==============
 
-Metapackages do not provide software directly but depend on a group of other related packages to provide a convenient installation mechanism for the complete group of packages. [#]_ [#]_
+Metapackages do not provide software directly but depend on a group of other related packages to provide a convenient installation mechanism for the complete group of packages.
+[#]_ [#]_
 Variants are a list of official metapackages for commonly useful groups of ROS packages.
 
 .. [#] https://wiki.debian.org/metapackage

diff --git a/source/Installation/Alternatives/Fedora-Development-Setup.rst b/source/Installation/Alternatives/Fedora-Development-Setup.rst
@@ -8,7 +8,8 @@ Fedora (source)
 How to setup the development environment?
 -----------------------------------------
 
-The following system dependencies are required to build ROS 2 on Fedora. They can be installed with ``dnf`` as follows:
+The following system dependencies are required to build ROS 2 on Fedora.
+They can be installed with ``dnf`` as follows:
 
 .. code-block:: bash
 

diff --git a/source/Installation/Alternatives/RHEL-Development-Setup.rst b/source/Installation/Alternatives/RHEL-Development-Setup.rst
@@ -39,7 +39,8 @@ They can be enabled by running:
    sudo dnf install 'dnf-command(config-manager)' epel-release -y
    sudo dnf config-manager --set-enabled powertools
 
-.. note:: This step may be slightly different depending on the distribution you are using. Check the EPEL documentation: https://docs.fedoraproject.org/en-US/epel/#_quickstart
+.. note:: This step may be slightly different depending on the distribution you are using.
+          `Check the EPEL documentation <https://docs.fedoraproject.org/en-US/epel/#_quickstart>`_
 
 
 Install development tools and ROS tools
@@ -175,7 +176,8 @@ See the :doc:`guide <../../How-To-Guides/Working-with-multiple-RMW-implementatio
 Alternate compilers
 -------------------
 
-Using a different compiler besides gcc to compile ROS 2 is easy. If you set the environment variables ``CC`` and ``CXX`` to executables for a working C and C++ compiler, respectively, and retrigger CMake configuration (by using ``--force-cmake-config`` or by deleting the packages you want to be affected), CMake will reconfigure and use the different compiler.
+Using a different compiler besides gcc to compile ROS 2 is easy.
+If you set the environment variables ``CC`` and ``CXX`` to executables for a working C and C++ compiler, respectively, and retrigger CMake configuration (by using ``--force-cmake-config`` or by deleting the packages you want to be affected), CMake will reconfigure and use the different compiler.
 
 Clang
 ^^^^^

diff --git a/source/Installation/Alternatives/RHEL-Install-Binary.rst b/source/Installation/Alternatives/RHEL-Install-Binary.rst
@@ -31,7 +31,8 @@ They can be enabled by running:
    sudo dnf install 'dnf-command(config-manager)' epel-release -y
    sudo dnf config-manager --set-enabled powertools
 
-.. note:: This step may be slightly different depending on the distribution you are using. Check the EPEL documentation: https://docs.fedoraproject.org/en-US/epel/#_quickstart
+.. note:: This step may be slightly different depending on the distribution you are using.
+          `Check the EPEL documentation <https://docs.fedoraproject.org/en-US/epel/#_quickstart>`_
 
 Installing prerequisites
 ------------------------

diff --git a/source/Installation/Alternatives/Ubuntu-Development-Setup.rst b/source/Installation/Alternatives/Ubuntu-Development-Setup.rst
@@ -187,7 +187,8 @@ Continue with the :doc:`tutorials and demos <../../Tutorials>` to configure your
 
 Using the ROS 1 bridge
 ----------------------
-The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa. See the dedicated `documentation <https://github.com/ros2/ros1_bridge/blob/master/README.md>`__ on how to build and use the ROS 1 bridge.
+The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa.
+See the dedicated `documentation <https://github.com/ros2/ros1_bridge/blob/master/README.md>`__ on how to build and use the ROS 1 bridge.
 
 Additional RMW implementations (optional)
 -----------------------------------------

diff --git a/source/Installation/Alternatives/Ubuntu-Install-Binary.rst b/source/Installation/Alternatives/Ubuntu-Install-Binary.rst
@@ -126,7 +126,8 @@ Continue with the :doc:`tutorials and demos <../../Tutorials>` to configure your
 
 Using the ROS 1 bridge
 ----------------------
-The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa. See the dedicated `documentation <https://github.com/ros2/ros1_bridge/blob/master/README.md>`__ on how to build and use the ROS 1 bridge.
+The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa.
+See the dedicated `documentation <https://github.com/ros2/ros1_bridge/blob/master/README.md>`__ on how to build and use the ROS 1 bridge.
 
 Additional RMW implementations (optional)
 -----------------------------------------

diff --git a/source/Installation/Alternatives/Windows-Development-Setup.rst b/source/Installation/Alternatives/Windows-Development-Setup.rst
@@ -70,7 +70,7 @@ First setup a development folder, for example ``C:\{DISTRO}``:
 .. note::
 
    It is very important that the chosen path is short, due to the short default Windows path limits (260 characters).
-   To allow longer paths, see https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry.
+   To allow longer paths, see `maximum-file-path-limitation <https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry>`__.
 
 .. code-block:: bash
 
@@ -124,7 +124,7 @@ Start a command shell and source the ROS 2 setup file to set up the workspace:
 
 This will automatically set up the environment for any DDS vendors that support was built for.
 
-It is normal that the previous command, if nothing else went wrong, outputs "The system cannot find the path specified." exactly once.
+It is normal that the previous command, if nothing else went wrong, outputs ``The system cannot find the path specified.`` exactly once.
 
 Test and run
 ------------
@@ -204,7 +204,7 @@ If you want to be able to run all the tests in Debug mode, you'll need to instal
 * You'll need to quit and restart the command prompt after installing the above.
 * Get and extract the Python 3.8.3 source from the ``tgz``:
 
-  * https://www.python.org/ftp/python/3.8.3/Python-3.8.3.tgz
+  * `Python-3.8.3 <https://www.python.org/ftp/python/3.8.3/Python-3.8.3.tgz>`__
   * To keep these instructions concise, please extract it to ``C:\dev\Python-3.8.3``
 
 * Now, build the Python source in debug mode from a Visual Studio command prompt:
@@ -256,7 +256,7 @@ If you want to be able to run all the tests in Debug mode, you'll need to instal
    python -m pip uninstall numpy lxml
    python -m pip install numpy lxml
 
-* To create executables python scripts(.exe), python_d should be used to invoke colcon
+* To create executables python scripts(``.exe``), python_d should be used to invoke colcon
 
 .. code-block:: bash
 

diff --git a/source/Installation/Alternatives/macOS-Development-Setup.rst b/source/Installation/Alternatives/macOS-Development-Setup.rst
@@ -178,7 +178,8 @@ Continue with the `tutorials and demos <../../Tutorials>` to configure your envi
 
 Using the ROS 1 bridge
 ----------------------
-The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa. See the dedicated `documentation <https://github.com/ros2/ros1_bridge/blob/master/README.md>`__ on how to build and use the ROS 1 bridge.
+The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa.
+See the dedicated `documentation <https://github.com/ros2/ros1_bridge/blob/master/README.md>`__ on how to build and use the ROS 1 bridge.
 
 Additional RMW implementations (optional)
 -----------------------------------------

diff --git a/source/Installation/DDS-Implementations.rst b/source/Installation/DDS-Implementations.rst
@@ -4,7 +4,7 @@ DDS implementations
 By default, ROS 2 uses DDS as its `middleware <https://design.ros2.org/articles/ros_on_dds.html>`__.
 It is compatible with multiple DDS or RTPS (the DDS wire protocol) vendors.
 There is currently support for eProsima's Fast DDS, RTI's Connext DDS, Eclipse Cyclone DDS, and GurumNetworks GurumDDS.
-See https://ros.org/reps/rep-2000.html for supported DDS vendors by distribution.
+See `REP-2000 <https://ros.org/reps/rep-2000.html>`__ for supported DDS vendors by distribution.
 
 The default DDS vendor is eProsima's Fast DDS.
 

diff --git a/source/Installation/DDS-Implementations/Install-Connext-Security-Plugins.rst b/source/Installation/DDS-Implementations/Install-Connext-Security-Plugins.rst
@@ -3,7 +3,8 @@ Connext security plugins
 
 The Connext DDS Libraries are included with ROS 2 under a `non-commercial
 license <https://www.rti.com/ncl>`__ and do not include the security
-plug-in libraries. These libraries are available in the commercial,
+plug-in libraries.
+These libraries are available in the commercial,
 university and research license versions of RTI Connext DDS Pro, which
 is bundled with tools for system debugging, monitoring, record/replay,
 etc.
@@ -13,7 +14,8 @@ The Connext DDS Evaluation Version (6.0.1) includes the security plugins, and ca
 A video walk-thru of this installation (tools and security plug-ins) is
 available
 `here <https://www.rti.com/gettingstarted/installwindows_secure>`__ at
-the RTI website. The steps are:
+the RTI website.
+The steps are:
 
 **Install Connext DDS Pro (Host)**
 This is a host-specific installer application (for Windows, Linux, MacOS) to install a 'Host' bundle which includes the Launcher, tools, and other software services.
@@ -27,23 +29,26 @@ The Launcher is used to install target libraries, security plugins, and other la
 
    Launcher Image
 
-The 'RTI Package Installer' is used to install '.rtipkg' files -- target
-libraries, security plug-ins, etc. Open the Package Installer and select
-all of the .rtipkg files that were included in the Connext DDS Secure
+The 'RTI Package Installer' is used to install ``.rtipkg`` files -- target
+libraries, security plug-ins, etc.
+Open the Package Installer and select
+all of the ``.rtipkg`` files that were included in the Connext DDS Secure
 bundle for installation:
 
- * Target Libraries - such as: rti\_connext\_dds-[version]-pro-target-[toolchain].rtipkg
- * Security Plugin Host - such as: rti\_security\_plugins-[version]-host-[toolchain].rtipkg
- * Security Plugin Target - such as: rti\_security\_plugins-[version]-target-[toolchain].rtipkg
- * OpenSSL Host - such as: openssl-1.0.2x-[version]-host-[toolchain].rtipkg
+ * Target Libraries - such as: ``rti_connext_dds-[version]-pro-target-[toolchain].rtipkg``
+ * Security Plugin Host - such as: ``rti_security_plugins-[version]-host-[toolchain].rtipkg``
+ * Security Plugin Target - such as: ``rti_security_plugins-[version]-target-[toolchain].rtipkg``
+ * OpenSSL Host - such as: ``openssl-1.0.2x-[version]-host-[toolchain].rtipkg``
 
 **Extract and Install OpenSSL**
-This is included as an archive (.zip or
+This is included as an archive (``.zip`` or
 otherwise) and can be simply extracted and copied to a convenient
-location on your host computer. As a suggestion, this could also be
-installed into the 'rti\_connext\_dds-[version]' directory in your home
+location on your host computer.
+As a suggestion, this could also be
+installed into the ``rti_connext_dds-[version]`` directory in your home
 directory space (this was created during installation of the RTI host
-tools). Note: this directory location may need to be placed in your PATH
+tools).
+Note: this directory location may need to be placed in your PATH
 environment variable.
 See the `RTI Security Plugins Getting Started Guide <https://community.rti.com/static/documentation/connext-dds/6.0.1/doc/manuals/connext_dds/dds_security/RTI_SecurityPlugins_GettingStarted.pdf>`__ for more information.
 

diff --git a/source/Installation/DDS-Implementations/Install-Connext-University-Eval.rst b/source/Installation/DDS-Implementations/Install-Connext-University-Eval.rst
@@ -6,7 +6,8 @@ RTI Connext DDS
    :local:
 
 A full-suite installation of RTI Connext DDS is available for many additional platforms, for universities, evaluation, or purchase.
-This installation includes diagnostic tools, layered services, and security.  See below for installation details.
+This installation includes diagnostic tools, layered services, and security.
+See below for installation details.
 
 RTI University Program
 ----------------------
@@ -23,8 +24,10 @@ To install RTI Connext DDS **version 6.0.1** Evaluation:
  * Visit the `RTI Free Trial (6.0.1) site <https://www.rti.com/free-trial>`__.
  * Download the version(s) to match your environment.
  * Contact [email protected] for an evaluation license.
- * Install RTI Connext 6.0.1 by running the installation program.  When finished, it will run the RTI Launcher.
- * Use the RTI Launcher to install the license file (rti_license.dat) if needed.  The launcher may also be used to launch the diagnostic tools and services.
+ * Install RTI Connext 6.0.1 by running the installation program.
+   When finished, it will run the RTI Launcher.
+ * Use the RTI Launcher to install the license file (rti_license.dat) if needed.
+   The launcher may also be used to launch the diagnostic tools and services.
 
 Detailed instructions for each platform are provided below.
 

diff --git a/source/Installation/DDS-Implementations/Working-with-GurumNetworks-GurumDDS.rst b/source/Installation/DDS-Implementations/Working-with-GurumNetworks-GurumDDS.rst
@@ -4,7 +4,8 @@
 
 GurumNetworks GurumDDS
 ======================
-``rmw_gurumdds`` is an implementation of the ROS middleware interface using GurumNetworks GurumDDS. For more information about GurumDDS, visit the `GurumNetworks website <https://gurum.cc/index_eng>`_.
+``rmw_gurumdds`` is an implementation of the ROS middleware interface using GurumNetworks GurumDDS.
+For more information about GurumDDS, visit the `GurumNetworks website <https://gurum.cc/index_eng>`_.
 
 
 Prerequisites
@@ -16,9 +17,9 @@ Version Requirements (`see the README for details <https://github.com/ros2/rmw_g
 ================  ================
 ROS 2 Distro      GurumDDS Version
 ================  ================
-rolling           >= 3.2.0
-jazzy             >= 3.2.0
-humble            3.1.x
+rolling           ``>= 3.2.0``
+jazzy             ``>= 3.2.0``
+humble            ``3.1.x``
 ================  ================
 
 Deb packages of GurumDDS are provided in the ROS 2 apt repositories on Ubuntu.

diff --git a/source/Installation/RHEL-Install-RPMs.rst b/source/Installation/RHEL-Install-RPMs.rst
@@ -35,9 +35,10 @@ You will need to enable the EPEL repositories and the PowerTools repository:
    sudo dnf install 'dnf-command(config-manager)' epel-release -y
    sudo dnf config-manager --set-enabled powertools
 
-.. note:: This step may be slightly different depending on the distribution you are using. Check the EPEL documentation: https://docs.fedoraproject.org/en-US/epel/#_quickstart
+.. note:: This step may be slightly different depending on the distribution you are using.
+          `Check the EPEL documentation <https://docs.fedoraproject.org/en-US/epel/#_quickstart>`_
 
-Next, download the ROS 2 .repo file:
+Next, download the ROS 2 ``.repo`` file:
 
 .. code-block:: bash
 

diff --git a/source/Installation/Ubuntu-Install-Debs.rst b/source/Installation/Ubuntu-Install-Debs.rst
@@ -120,7 +120,8 @@ Continue with the :doc:`tutorials and demos <../../Tutorials>` to configure your
 
 Using the ROS 1 bridge
 ----------------------
-The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa. See the dedicated `documentation <https://github.com/ros2/ros1_bridge/blob/master/README.md>`__ on how to build and use the ROS 1 bridge.
+The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa.
+See the dedicated `documentation <https://github.com/ros2/ros1_bridge/blob/master/README.md>`__ on how to build and use the ROS 1 bridge.
 
 Additional RMW implementations (optional)
 -----------------------------------------

diff --git a/source/Installation/Windows-Install-Binary.rst b/source/Installation/Windows-Install-Binary.rst
@@ -53,7 +53,7 @@ Start a command shell and source the ROS 2 setup file to set up the workspace:
 
    call C:\dev\ros2_{DISTRO}\local_setup.bat
 
-It is normal that the previous command, if nothing else went wrong, outputs "The system cannot find the path specified." exactly once.
+It is normal that the previous command, if nothing else went wrong, outputs ``The system cannot find the path specified.`` exactly once.
 
 Try some examples
 -----------------