From a9284dc84c7a5a63f0b2811a9dd4670380b039d2 Mon Sep 17 00:00:00 2001 From: Murilo Marinho Date: Mon, 14 Sep 2026 19:17:00 +0100 Subject: [PATCH] Fix MEDIUM-severity tutorial issues - Update 11 stale ROS distro links (Humble/Foxy) to their Jazzy equivalents. Every target URL was verified to resolve on the current Jazzy docs, including the Jazzy reorganisations: * Understanding-ROS2-Parameters -> .../Understanding-ROS2-Parameters/ Understanding-ROS2-Parameters.html * Launch-Main.html -> Creating-Launch-Files.html (no longer exists on Jazzy) * About-Quality-of-Service-Settings -> Concepts/Intermediate/ * About-ROS-Interfaces -> Concepts/Basic/About-Interfaces * Concepts.html#quick-overview -> Concepts/Basic.html (anchor removed) * docs.ros2.org//api/... (old layout, now 404) -> docs.ros.org/en/jazzy/p/rclpy|tf2_ros/... * rclpy timer.hpp: humble -> jazzy branch - Add gazebo/other_content to the Gazebo toctree so the previously unreachable 'Gazebo and ROS2 structure' page is now reachable. - Remove three dead RST files (referenced by nothing): * docker/troubleshooting.rst (content already inlined in docker/index.rst) * the_pycharm_dependencies_warning.rst (orphaned + dangling :ref:) * the_section_is_optional.rst (orphaned) Co-authored-by: openhands --- docs/source/create_interface_package.rst | 2 +- docs/source/docker/troubleshooting.rst | 26 ------------------- docs/source/index.rst | 1 + docs/source/interfaces.rst | 2 +- docs/source/parameters_and_launch.rst | 8 +++--- docs/source/publishers_and_subscribers.rst | 4 +-- docs/source/python_node_explained.rst | 4 +-- .../the_pycharm_dependencies_warning.rst | 4 --- docs/source/the_section_is_optional.rst | 3 --- docs/source/transformations/tf2.rst | 2 +- 10 files changed, 12 insertions(+), 44 deletions(-) delete mode 100644 docs/source/docker/troubleshooting.rst delete mode 100644 docs/source/the_pycharm_dependencies_warning.rst delete mode 100644 docs/source/the_section_is_optional.rst diff --git a/docs/source/create_interface_package.rst b/docs/source/create_interface_package.rst index 1594f659..09285e27 100644 --- a/docs/source/create_interface_package.rst +++ b/docs/source/create_interface_package.rst @@ -112,7 +112,7 @@ The message file .. note:: - Here is a list of available `built-in types `_ for ROS2 interfaces. + Here is a list of available `built-in types `_ for ROS2 interfaces. Let us create a message file to transfer inspirational quotes between Nodes. For example, the one below. diff --git a/docs/source/docker/troubleshooting.rst b/docs/source/docker/troubleshooting.rst deleted file mode 100644 index a065782b..00000000 --- a/docs/source/docker/troubleshooting.rst +++ /dev/null @@ -1,26 +0,0 @@ -Troubleshooting :program:`docker` -================================= - - -.. include:: ../the_topic_is_under_heavy_construction.rst - -The standard shell is not interactive -+++++++++++++++++++++++++++++++++++++ - -When we start using :program:`ROS2` we get used to rely on `~/.bashrc` to define -environment variables and sometimes aliases. - -Unless explicitly said with flags such as ``-it``, docker does not run -bash in interactive mode. This means that it will not execute anything in :file:`~/.bashrc`. -It does not matter what you add, because the first few lines of :file:`~/.bashrc` check if -the shell is interactive and return if it's not. - -This example image that we use will run ``source /etc/bash_env`` in noninteractive shells. -However, it will not run for interactive shells and aliases that we define will not work. -Noninteractive shells by default do not expand aliases. - -The "easiest" solution is - -#. Set your :file:`Dockerfile` to source ``/etc/bash_env`` -#. Add ``source source /etc/bash_env`` to your :file:`~/.bashrc` exactly once. - diff --git a/docs/source/index.rst b/docs/source/index.rst index 5a583545..a43b7463 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -205,6 +205,7 @@ If you enjoyed this tutorial, please gazebo/usage gazebo/ros_gz_bridge gazebo/custom_nodes + gazebo/other_content .. toctree:: :caption: Navigation diff --git a/docs/source/interfaces.rst b/docs/source/interfaces.rst index eea1aa7f..bf55ae6d 100644 --- a/docs/source/interfaces.rst +++ b/docs/source/interfaces.rst @@ -7,7 +7,7 @@ ROS2 Interfaces (:program:`ros2 interface`) If by now you haven't particularly fallen in love with :program:`ROS2`, fear not. Indeed, we haven't done much so far that couldn't be achieved more easily by other means. -:program:`ROS2` begins to shine most in its interprocess communication, through what are called `ROS2 interfaces `_. +:program:`ROS2` begins to shine most in its interprocess communication, through what are called `ROS2 interfaces `_. In particular, the fact that we can easily interface Nodes written in Python and C++ is a strong selling point. :code:`Messages` are one of the three types of ROS2 interfaces. This will most likely be the standard of communication between Nodes in your packages. We will also see the bidirectional :code:`Services` and :code:`Actions`. diff --git a/docs/source/parameters_and_launch.rst b/docs/source/parameters_and_launch.rst index e144728f..52113868 100644 --- a/docs/source/parameters_and_launch.rst +++ b/docs/source/parameters_and_launch.rst @@ -3,7 +3,7 @@ Parameters and launch files: creating configurable Nodes The Nodes we have made in the past few sections are interesting because they take advantage of the interprocess communication provided by ROS2. -Other capabilities of ROS2 that we must take advantage of are `ROS2 parameters `_ and `ROS2 launch files `_. We can use them to modify the behavior of Nodes without having to modify their source code. +Other capabilities of ROS2 that we must take advantage of are `ROS2 parameters `_ and `ROS2 launch files `_. We can use them to modify the behavior of Nodes without having to modify their source code. For Python users, that might sound less appealing than for users of compiled languages. However, users of your package might not want nor be able to modify the source code directly, if the package is installable or part of a larger system with multiple users. @@ -74,7 +74,7 @@ Don't forget to declare the parameter! .. note:: - According to the `official documentation `_, it is possible to work with undeclared parameters, but + According to the `official documentation `_, it is possible to work with undeclared parameters, but I recommend against this for basic usage. It's easy to forget it, but :code:`Node.get_parameter()` will not work if the parameter was not first declared with :code:`Node.declare_parameter()`. Don't forget it! @@ -101,7 +101,7 @@ Continuously-obtained parameters .. note:: - According to the `official documentation `_, it is possible to assign + According to the `official documentation `_, it is possible to assign callbacks to manage changes in parameters. It is not the best-documented feature and has some caveats, so we will skip that for now. For parameters that we obtain continuously through the lifetime of the Node, we can, for example, declare them in the :code:`__init__` method, like so @@ -133,7 +133,7 @@ Truly configurable: using :file:`_launch.py` files However, my experience with these so far has been quite positive, because when using Python we have access to an entire ecosystem of tools to make the launch files smarter, whereas with the :abbr:`XML (Extensible Markup Language)`\ -based ones, if possible at all, we had to add hack on top of hack to achieve the same. -Differently from ROS1, in ROS2 we can use Python launch files. They are quite powerful, well documented, and mentioned first `in the official documentation `_, so we will use them instead of :abbr:`XML (Extensible Markup Language)` or :abbr:`YAML (YAML ain't markup language)` files. +Differently from ROS1, in ROS2 we can use Python launch files. They are quite powerful, well documented, and mentioned first `in the official documentation `_, so we will use them instead of :abbr:`XML (Extensible Markup Language)` or :abbr:`YAML (YAML ain't markup language)` files. (Once) create the :file:`launch` folder --------------------------------------- diff --git a/docs/source/publishers_and_subscribers.rst b/docs/source/publishers_and_subscribers.rst index 06fc8562..e50ce419 100644 --- a/docs/source/publishers_and_subscribers.rst +++ b/docs/source/publishers_and_subscribers.rst @@ -11,7 +11,7 @@ Then - A program that sends (publishes) information to the topic has one or more :code:`Publisher` \(s). - A program that reads (subscribes) information from a topic has one or more :code:`Subscriber` \(s). -Each Node can have any number of :code:`Publishers` and :code:`Subscribers` and a combination thereof, connecting to an arbitrary number of Nodes. This forms part of the connections in the so-called `ROS graph `_. An example is shown below. +Each Node can have any number of :code:`Publishers` and :code:`Subscribers` and a combination thereof, connecting to an arbitrary number of Nodes. This forms part of the connections in the so-called `ROS graph `_. An example is shown below. Diagram ------- @@ -165,7 +165,7 @@ The publisher must be created with the :code:`Node.create_publisher(...)` method |:code:`topic` | The topic through which the communication will occur. Can be arbitrarily chosen, but to make sense :code:`/amazing_quote`. | +--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ |:code:`qos_profile` | The simplest interpretation for this parameter is the maximum number of messages that will be stored in a buffer if your node (including :code:`spin(...)`) takes too long to process them. | -| | (See more on `docs for QoSProfile `_.) | +| | (See more on `docs for QoSProfile `_.) | +--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. warning:: diff --git a/docs/source/python_node_explained.rst b/docs/source/python_node_explained.rst index 704fe8f8..458cf7e8 100644 --- a/docs/source/python_node_explained.rst +++ b/docs/source/python_node_explained.rst @@ -39,7 +39,7 @@ Use a :code:`Timer` for periodic work (when using :code:`rclpy.spin()`) If the code relies on :code:`rclpy.spin()`, a Timer must be used for periodic work. -In its most basic usage, periodic tasks in ROS2 must be handled by a `Timer `_. +In its most basic usage, periodic tasks in ROS2 must be handled by a `Timer `_. To do so, have the node create it with the :code:`create_timer()` method, as follows. @@ -60,7 +60,7 @@ In ROS2, the logging methods, i.e. :code:`self.get_logger().info()`, are methods Where the ROS2 magic happens: :code:`rclpy.init()` and :code:`rclpy.spin()` ---------------------------------------------------------------------------- -All the ROS2 magic happens in some sort of :code:`spin()` method. It is called this way because the :code:`spin()` method will constantly loop (or spin) through **items of work**, e.g. scheduled Timer callbacks. All the **items of work** will only be effectively executed when an **executor** runs through it. For simple Nodes, such as the one in this example, the **global** executor is implicitly used. You can read a bit more about that `here `_. +All the ROS2 magic happens in some sort of :code:`spin()` method. It is called this way because the :code:`spin()` method will constantly loop (or spin) through **items of work**, e.g. scheduled Timer callbacks. All the **items of work** will only be effectively executed when an **executor** runs through it. For simple Nodes, such as the one in this example, the **global** executor is implicitly used. You can read a bit more about that `here `_. Anyhow, the point is that nothing related to ROS2 will happen unless the two following methods are called. First, :code:`rclpy.init()` is going to initialize a bunch of ROS2 elements behind the curtains, whereas :code:`rclpy.spin()` will `block `_ the program and, well, **spin** through Timer callbacks forever. There are alternative ways to :code:`spin()`, but we will not discuss them right now. diff --git a/docs/source/the_pycharm_dependencies_warning.rst b/docs/source/the_pycharm_dependencies_warning.rst deleted file mode 100644 index 8ce4a893..00000000 --- a/docs/source/the_pycharm_dependencies_warning.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. warning:: - - At this point, :program:`PyCharm` might be unable to find the dependencies. - Proceed as described in :ref:`PyCharm is not finding the dependencies`. diff --git a/docs/source/the_section_is_optional.rst b/docs/source/the_section_is_optional.rst deleted file mode 100644 index 476a2bef..00000000 --- a/docs/source/the_section_is_optional.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. note:: - - This section is optional, the ROS2 tutorial starts at :ref:`ROS2 installation`. diff --git a/docs/source/transformations/tf2.rst b/docs/source/transformations/tf2.rst index 5e2a064c..f636d603 100644 --- a/docs/source/transformations/tf2.rst +++ b/docs/source/transformations/tf2.rst @@ -170,7 +170,7 @@ previous step. We will call ``lookup_transform`` and it will need the parent fra and the time of lookup. We add exception handling in case the transform is not available or not available in the time requested. -The object created with ``rclpy.time.Time()`` is `equivalent to a time of zero `_, and ``lookup_transform`` `returns the latest transformation available `_. +The object created with ``rclpy.time.Time()`` is `equivalent to a time of zero `_, and ``lookup_transform`` `returns the latest transformation available `_. .. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_tf2/python_package_that_uses_tf2/tf2_listener_node.py :language: python