ros2 · fujitatomoya · Mar 13, 2025 · Aug 6, 2024 · Aug 6, 2024 · Aug 7, 2024
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|^)(\.)(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
@@ -207,4 +207,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/RHEL-Development-Setup.rst b/source/Installation/Alternatives/RHEL-Development-Setup.rst
@@ -43,7 +43,8 @@ Enable required repositories
       sudo dnf install 'dnf-command(config-manager)' epel-release -y
       sudo dnf config-manager --set-enabled crb
 
-    .. 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>`_
 
   .. group-tab:: Fedora
 
@@ -177,7 +178,8 @@ Continue with the :doc:`tutorials and demos <../../Tutorials>` to configure your
 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
@@ -41,7 +41,8 @@ They can be enabled by running:
    sudo dnf install 'dnf-command(config-manager)' epel-release -y
    sudo dnf config-manager --set-enabled crb
 
-.. 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 prerequisites
 ^^^^^^^^^^^^^^^^^^^^^

diff --git a/source/Installation/Alternatives/Windows-Development-Setup.rst b/source/Installation/Alternatives/Windows-Development-Setup.rst
@@ -48,7 +48,7 @@ Using the powershell session you started above, run the following:
 
    New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
 
-You can read more about this limitation at https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry.
+You can read more about this limitation in `Microsoft's documentation <https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry>`__.
 
 
 Install prerequisites
@@ -192,7 +192,7 @@ This is required in every command prompt you open to setup the ROS 2 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.
 
 Try some examples
 -----------------

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 license@rti.com 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
@@ -37,9 +37,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 crb
 
-.. 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/Windows-Install-Binary.rst b/source/Installation/Windows-Install-Binary.rst
@@ -107,7 +107,7 @@ This is required in every command prompt you open to setup the ROS 2 workspace:
 
    call 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
 -----------------

diff --git a/source/Installation/_RHEL-Set-Locale.rst b/source/Installation/_RHEL-Set-Locale.rst
@@ -1,6 +1,7 @@
 Make sure you have a locale which supports ``UTF-8``.
 If you are in a minimal environment (such as a docker container), the locale may be something minimal like ``C``.
-We test with the following settings. However, it should be fine if you're using a different UTF-8 supported locale.
+We test with the following settings.
+However, it should be fine if you're using a different UTF-8 supported locale.
 
 .. code-block:: bash
 

diff --git a/source/Installation/_Ubuntu-Set-Locale.rst b/source/Installation/_Ubuntu-Set-Locale.rst
@@ -1,6 +1,7 @@
 Make sure you have a locale which supports ``UTF-8``.
 If you are in a minimal environment (such as a docker container), the locale may be something minimal like ``POSIX``.
-We test with the following settings. However, it should be fine if you're using a different UTF-8 supported locale.
+We test with the following settings.
+However, it should be fine if you're using a different UTF-8 supported locale.
 
 .. code-block:: bash
 

diff --git a/source/Installation/_rosdep_Linux_Mint.rst b/source/Installation/_rosdep_Linux_Mint.rst
@@ -1 +1,2 @@
-**Note**: If you're using a distribution that is based on Ubuntu (like Linux Mint) but does not identify itself as such, you'll get an error message like ``Unsupported OS [mint]``. In this case append ``--os=ubuntu:noble`` to the above command.
+**Note**: If you're using a distribution that is based on Ubuntu (like Linux Mint) but does not identify itself as such, you'll get an error message like ``Unsupported OS [mint]``.
+In this case append ``--os=ubuntu:noble`` to the above command.
diff --git a/source/The-ROS2-Project/Contributing/Build-Farms.rst b/source/The-ROS2-Project/Contributing/Build-Farms.rst
@@ -96,10 +96,11 @@ Frequency Asked Questions (FAQ) and Troubleshooting
 
 #. **I seem to be missing a dependency, how do I find out which one?**
 
-   You basically have two options, a. is easier but may take several iterations, b. is more
-   elaborate and gives you the full insight as well as local debugging.
+   You basically have two options:
+   Option a is easier but may take several iterations;
+   Option b is more elaborate and gives you the full insight as well as local debugging.
 
-   a) Inspect the release job that raised the issue (see 1.) and localize the cmake dependency issue.
+   a) Inspect the release job that raised the issue (see above question) and localize the cmake dependency issue.
       To do so, browse to the cmake section, e.g., navigate to the *build binarydeb*
       section through the menu on the left in case of a Ubuntu/Debian build job.
       The *CMake Error* will typically hint at a dependency required by the cmake configuration but missing in the `package manifest`_.