Merge remote-tracking branch 'origin/rolling' into rolling

.devcontainer/devcontainer.json

@@ -5,7 +5,7 @@
 	},
 	"workspaceMount": "source=${localWorkspaceFolder},target=/tmp/doc_repository,type=bind",
 	"workspaceFolder": "/tmp/doc_repository",
-	"postCreateCommand": "pip3 install --no-warn-script-location --user -r requirements.txt -c constraints.txt --break-system-packages",
+	"postCreateCommand": "pip3 install --no-warn-script-location --user -r requirements.txt -c constraints.txt",
 	"features": {
 		"ghcr.io/devcontainers/features/git:1": {}
 	},

.github/workflows/test.yml

@@ -37,6 +37,23 @@ jobs:
       - name: Lint
         run: make lint
 
+  spellcheck:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies with pip
+        run: pip install --no-warn-script-location --user -r requirements.txt -c constraints.txt
+
+      - name: Spellcheck
+        run: make spellcheck
+
   build:
     needs: [test, lint]
     runs-on: ubuntu-22.04

Makefile

@@ -28,6 +28,9 @@ lint:
 test:
 	doc8 --ignore D001 --ignore-path build
 
+spellcheck:
+	git ls-files '*.md' '*.rst' | xargs codespell --config codespell.cfg
+
 linkcheck:
 	$(BUILD) -b linkcheck $(OPTS) $(SOURCE) $(LINKCHECKDIR)
 	@echo

README.md

@@ -51,6 +51,15 @@ For local testing of the current tree use:
 
 `sensible-browser build/html/index.html`
 
+### Spelling Check
+
+To check the spelling, use:
+
+`make spellcheck`
+
+> [!NOTE]
+> If that detects specific words that need to be ignored, add it to [codespell_whitelist](./codespell_whitelist.txt).
+
 ### Deployment test
 
 To test building the multisite version deployed to the website use:

codespell.cfg

@@ -0,0 +1,15 @@
+[codespell]
+
+# Enable built-in dictionaries/rules.
+# See more details for https://github.com/codespell-project/codespell/tree/main/codespell_lib/data.
+builtin = clear,rare,informal,code
+
+# Ignore words listed in this file.
+ignore-words = codespell_whitelist.txt
+
+# Skip checking files in this directory.
+# This folder is ignored for a couple of reasons.
+# *-Changelog.rst files are generated by commit history that could include some misspellings,
+# but we should keep the original commit messages here.
+# Besides, it includes names of authors and contributors, which compile up the false alarms.
+skip = source/Releases/*

codespell_whitelist.txt

@@ -0,0 +1,4 @@
+empy
+ws
+lets
+jupyter

docker/image/Dockerfile

@@ -3,7 +3,7 @@
 #
 # docker build -f docker/image/Dockerfile .
 
-FROM ubuntu:noble
+FROM ubuntu:jammy
 
 ARG user=rosindex
 ARG uid=1000

requirements.txt

@@ -1,3 +1,4 @@
+codespell
 doc8
 docutils
 pip

source/Concepts/Basic/About-Client-Libraries.rst

@@ -77,7 +77,8 @@ While the C++ and Python client libraries are maintained by the core ROS 2 team,
 * `C <https://github.com/ros2/rclc>`__  ``rclc`` does not put a layer on top of rcl but complements rcl to make rcl+rclc a feature-complete client library in C. See `micro.ros.org <https://micro.ros.org/>`__ for tutorials.
 * `JVM and Android <https://github.com/ros2-java>`__ Java and Android bindings for ROS 2.
 * `.NET Core, UWP and C# <https://github.com/esteve/ros2_dotnet>`__ This is a collection of projects (bindings, code generator, examples and more) for writing ROS 2 applications for .NET Core and .NET Standard.
-* `Node.js <https://www.npmjs.com/package/rclnodejs>`__ rclnodejs is a Node.js client for ROS 2. It provides a simple and easy JavaScript API for ROS 2 programming.
+* `Node.js <https://www.npmjs.com/package/rclnodejs>`__ rclnodejs is a Node.js client for ROS 2.
+  It provides a simple and easy JavaScript API for ROS 2 programming.
 * `Rust <https://github.com/ros2-rust/ros2_rust>`__ This is a set of projects (the rclrs client library, code generator, examples and more) that enables developers to write ROS 2 applications in Rust.
 * `Flutter and Dart <https://github.com/rcldart>`__ Flutter and Dart bindings for ROS 2.
 

source/Concepts/Basic/About-Interfaces.rst

@@ -18,9 +18,13 @@ This description makes it easy for ROS tools to automatically generate source co
 
 In this document we will describe the supported types:
 
-* msg: ``.msg`` files are simple text files that describe the fields of a ROS message. They are used to generate source code for messages in different languages.
-* srv: ``.srv`` files describe a service. They are composed of two parts: a request and a response. The request and response are message declarations.
-* action: ``.action`` files describe actions. They are composed of three parts: a goal, a result, and feedback.
+* msg: ``.msg`` files are simple text files that describe the fields of a ROS message.
+  They are used to generate source code for messages in different languages.
+* srv: ``.srv`` files describe a service.
+  They are composed of two parts: a request and a response.
+  The request and response are message declarations.
+* action: ``.action`` files describe actions.
+  They are composed of three parts: a goal, a result, and feedback.
   Each part is a message declaration itself.
 
 Messages
@@ -207,7 +211,7 @@ For example:
 Constants
 ^^^^^^^^^
 
-Each constant definition is like a field description with a default value, except that this value can never be changed programatically.
+Each constant definition is like a field description with a default value, except that this value can never be changed programmatically.
 This value assignment is indicated by use of an equal '=' sign, e.g.
 
 .. code-block:: bash

source/Concepts/Basic/About-Parameters.rst

@@ -89,11 +89,14 @@ The services that are created by default are:
 * ``/node_name/get_parameters``: Uses a service type of ``rcl_interfaces/srv/GetParameters``.
   Given a list of parameter names, returns a list of parameter values associated with the parameters.
 * ``/node_name/list_parameters``: Uses a service type of ``rcl_interfaces/srv/ListParameters``.
-  Given an optional list of parameter prefixes, returns a list of the available parameters with that prefix.  If the prefixes are empty, returns all parameters.
+  Given an optional list of parameter prefixes, returns a list of the available parameters with that prefix.
+  If the prefixes are empty, returns all parameters.
 * ``/node_name/set_parameters``: Uses a service type of ``rcl_interfaces/srv/SetParameters``.
-  Given a list of parameter names and values, attempts to set the parameters on the node.  Returns a list of results from trying to set each parameter; some of them may have succeeded and some may have failed.
+  Given a list of parameter names and values, attempts to set the parameters on the node.
+  Returns a list of results from trying to set each parameter; some of them may have succeeded and some may have failed.
 * ``/node_name/set_parameters_atomically``: Uses a service type of ``rcl_interfaces/srv/SetParametersAtomically``.
-  Given a list of parameter names and values, attempts to set the parameters on the node.  Returns a single result from trying to set all parameters, so if one failed, all of them failed.
+  Given a list of parameter names and values, attempts to set the parameters on the node.
+  Returns a single result from trying to set all parameters, so if one failed, all of them failed.
 
 Setting initial parameter values when running a node
 ----------------------------------------------------
@@ -119,16 +122,4 @@ Migrating from ROS 1
 
 The :doc:`Launch file migration guide <../../How-To-Guides/Migrating-from-ROS1/Migrating-Launch-Files>` explains how to migrate ``param`` and ``rosparam`` launch tags from ROS 1 to ROS 2.
 
-The :doc:`YAML parameter file migration guide <../../How-To-Guides/Migrating-from-ROS1/Migrating-Parameters>` explains how to migrate parameter files from ROS 1 to ROS 2.
-
-In ROS 1, the ``roscore`` acted like a global parameter blackboard where all nodes could get and set parameters.
-Since there is no central ``roscore`` in ROS 2, that functionality no longer exists.
-The recommended approach in ROS 2 is to use per-node parameters that are closely tied to the nodes that use them.
-If a global blackboard is still needed, it is possible to create a dedicated node for this purpose.
-ROS 2 ships with one in the ``ros-{DISTRO}-demo-nodes-cpp`` package called ``parameter_blackboard``; it can be run with:
-
-.. code-block:: console
-
-   ros2 run demo_nodes_cpp parameter_blackboard
-
-The code for the ``parameter_blackboard`` is `here <https://github.com/ros2/demos/blob/{REPOS_FILE_BRANCH}/demo_nodes_cpp/src/parameters/parameter_blackboard.cpp>`__.
+The :doc:`Migration guide <../../How-To-Guides/Migrating-from-ROS1/Migrating-Parameters>` explains how to migrate parameter from ROS 1 to ROS 2.

source/Concepts/Basic/About-Topics.rst

@@ -14,7 +14,7 @@ Publish/Subscribe
 -----------------
 
 A publish/subscribe system is one in which there are producers of data (publishers) and consumers of data (subscribers).
-The publishers and subscribers know how to contact each other through the concept of a "topic", which is a common name so that the entites can find each other.
+The publishers and subscribers know how to contact each other through the concept of a "topic", which is a common name so that the entities can find each other.
 For instance, when you create a publisher, you must also give it a string that is the name of the topic; the same goes for the subscriber.
 Any publishers and subscribers that are on the same topic name can directly communicate with each other.
 There may be zero or more publishers and zero or more subscribers on any particular topic.
@@ -48,4 +48,7 @@ That has two meanings in this context:
 
    Then the code will ensure that ``field1`` is always an unsigned integer and that ``field2`` is always a string.
 
-2. The semantics of each field are well-defined.  There is no automated mechanism to ensure this, but all of the core ROS types have strong semantics associated with them.  For instance, the IMU message contains a 3-dimensional vector for the measured angular velocity, and each of the dimensions is specified to be in radians/second.  Other interpretations should not be placed into the message.
+2. The semantics of each field are well-defined.
+   There is no automated mechanism to ensure this, but all of the core ROS types have strong semantics associated with them.
+   For instance, the IMU message contains a 3-dimensional vector for the measured angular velocity, and each of the dimensions is specified to be in radians/second.
+   Other interpretations should not be placed into the message.

source/Concepts/Intermediate/About-Cross-Compilation.rst

@@ -22,7 +22,9 @@ How does it work ?
 Cross-compiling simple software (e.g. no dependencies on external libraries) is relatively simple and only requiring a cross-compiler toolchain to be used instead of the native toolchain.
 
 There are a number of factors which make this process more complex:
- - The software being built must support the target architecture. Architecture specific code must be properly isolated and enabled during the build according to the target architecture. Examples include assembly code.
+ - The software being built must support the target architecture.
+   Architecture specific code must be properly isolated and enabled during the build according to the target architecture.
+   Examples include assembly code.
  - All dependencies (e.g. libraries) must be present, either as pre-built or cross-compiled packages, before the target software using them is cross-compiled.
  - When building software stacks (as opposed to standalone software) using build tools (e.g. colcon), it is expected that the build tool provides a mechanism to allow the developer to enable cross-compilation on the underlying build system used by each piece of software in the stack.
 

source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst

@@ -37,19 +37,24 @@ Supported RMW implementations
    * - eProsima *Fast DDS*
      - Apache 2
      - ``rmw_fastrtps_cpp``
-     - Full support. Default RMW. Packaged with binary releases.
+     - Full support.
+       Default RMW.
+       Packaged with binary releases.
    * - Eclipse *Cyclone DDS*
      - Eclipse Public License v2.0
      - ``rmw_cyclonedds_cpp``
-     - Full support. Packaged with binary releases.
+     - Full support.
+       Packaged with binary releases.
    * - RTI *Connext DDS*
      - commercial, research
      - ``rmw_connextdds``
-     - Full support. Support included in binaries, but Connext installed separately.
+     - Full support.
+       Support included in binaries, but Connext installed separately.
    * - GurumNetworks *GurumDDS*
      - commercial
      - ``rmw_gurumdds_cpp``
-     - Community support. Support included in binaries, but GurumDDS installed separately.
+     - Community support.
+       Support included in binaries, but GurumDDS installed separately.
 
 For practical information on working with multiple RMW implementations, see the :doc:`"Working with multiple RMW implementations" <../../How-To-Guides/Working-with-multiple-RMW-implementations>` tutorial.
 

source/Concepts/Intermediate/About-Executors.rst

@@ -169,7 +169,8 @@ The following flow diagram visualizes this scheduling semantics.
 .. image:: ../images/executors_scheduling_semantics.png
 
 This semantics was first described in a `paper by Casini et al. at ECRTS 2019 <https://drops.dagstuhl.de/opus/volltexte/2019/10743/pdf/LIPIcs-ECRTS-2019-6.pdf>`_.
-(Note: The paper also explains that timer events are prioritized over all other messages. `This prioritization was removed in Eloquent. <https://github.com/ros2/rclcpp/pull/841>`_)
+(Note: The paper also explains that timer events are prioritized over all other messages.
+`This prioritization was removed in Eloquent. <https://github.com/ros2/rclcpp/pull/841>`_)
 
 
 Outlook
@@ -198,6 +199,12 @@ These issues have been partially addressed by the following developments:
 Further information
 -------------------
 
-* Michael Pöhnl et al.: `"ROS 2 Executor: How to make it efficient, real-time and deterministic?" <https://www.apex.ai/roscon-21>`_. Workshop at ROS World 2021. Virtual event. 19 October 2021.
-* Ralph Lange: `"Advanced Execution Management with ROS 2" <https://www.youtube.com/watch?v=Sz-nllmtcc8&t=109s>`_. ROS Industrial Conference. Virtual event. 16 December 2020.
+* Michael Pöhnl et al.: `"ROS 2 Executor: How to make it efficient, real-time and deterministic?" <https://www.apex.ai/roscon-21>`_.
+  Workshop at ROS World 2021.
+  Virtual event.
+  19 October 2021.
+* Ralph Lange: `"Advanced Execution Management with ROS 2" <https://www.youtube.com/watch?v=Sz-nllmtcc8&t=109s>`_.
+  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.

source/Concepts/Intermediate/About-RQt.rst

@@ -56,7 +56,7 @@ RQt Components Structure
 
 RQt consists of two metapackages:
 
-* *rqt* - core infrastucture modules.
+* *rqt* - core infrastructure modules.
 * *rqt_common_plugins* - Commonly useful debugging tools.
 
 Advantage of RQt framework
@@ -72,7 +72,7 @@ Compared to building your own GUIs from scratch:
 From system architecture's perspective:
 
 * Support multi-platform (basically wherever `QT <http://qt-project.org/>`__ and ROS run) and multi-language (``Python``, ``C++``).
-* Manageable lifecycle: RQt plugins using a common API makes maintainance & reuse easier.
+* Manageable lifecycle: RQt plugins using a common API makes maintenance & reuse easier.
 
 
 Further Reading

source/Contact.rst

@@ -57,9 +57,14 @@ When filing an issue, please make sure to:
 Describe exactly what you were doing or are trying to do, and exactly what, if anything, went wrong.
 If following a tutorial or online instructions provide a link to the specific instructions.
 
-* Use a descriptive headline or subject line. Bad: "rviz doesn't work". 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. Cut and paste them directly from the terminal window to which they were printed. Please do not re-type or include a screenshot.
+* Use a descriptive headline or subject line.
+  Bad: "rviz doesn't work".
+  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.
+  Cut and paste them directly from the terminal window to which they were printed.
+  Please do not re-type or include a screenshot.
 * In case of a bug consider providing a `short, self contained, correct (compilable), example <http://sscce.org/>`__.
 * When discussing any compiling/linking/installation issues, also provide the compiler version
 

source/Glossary.rst

@@ -8,7 +8,11 @@ Glossary of terms used throughout this documentation:
 .. glossary::
 
    API
-       An API, or Application Programming Interface, is an interface that is provided by an "application", which in this case is usually a shared library or other language appropriate shared resource. APIs are made up of files that define a contract between the software using the interface and the software providing the interface. These files typically manifest as header files in C and C++ and as Python files in Python. In either case it is important that APIs are grouped and described in documentation and that they are declared as either public or private. Public interfaces are subject to change rules and changes to the public interfaces prompt a new version number of the software that provides them.
+       An API, or Application Programming Interface, is an interface that is provided by an "application", which in this case is usually a shared library or other language appropriate shared resource.
+       APIs are made up of files that define a contract between the software using the interface and the software providing the interface.
+       These files typically manifest as header files in C and C++ and as Python files in Python.
+       In either case it is important that APIs are grouped and described in documentation and that they are declared as either public or private.
+       Public interfaces are subject to change rules and changes to the public interfaces prompt a new version number of the software that provides them.
 
    client_library
        A client library is an :term:`API` that provides access to the ROS graph using primitive middleware concepts like Topics, Services, and Actions.
@@ -17,15 +21,17 @@ Glossary of terms used throughout this documentation:
        A single unit of software, including source code, build system files, documentation, tests, and other associated resources.
 
    REP
-        ROS Enhancement Proposal. A document that describes an enhancement, standardization, or convention for the ROS community.
+        ROS Enhancement Proposal.
+        A document that describes an enhancement, standardization, or convention for the ROS community.
         The associated REP approval process allows the community to iterate on a proposal until some consensus has been made, at which point it can be ratified and implemented, which then becomes documentation.
         All REPs are viewable from the `REP index <http://www.ros.org/reps/rep-0000.html>`_.
 
    VCS
        Version Control System, such as CVS, SVN, git, mercurial, etc...
 
    rclcpp
-       The C++ specific :term:`Client Library <client_library>` for ROS. This includes any middleware related APIs as well as the related message generation of C++ data structures based on interface definitions like Messages, Services, and Actions.
+       The C++ specific :term:`Client Library <client_library>` for ROS.
+       This includes any middleware related APIs as well as the related message generation of C++ data structures based on interface definitions like Messages, Services, and Actions.
 
    repository
        A collection of packages usually managed using a :term:`VCS` like git or mercurial and usually hosted on a site like GitHub or BitBucket.