Skip to content

Fix MEDIUM-severity issues: stale Jazzy links, dead pages - #35

Merged
mmmarinho merged 1 commit into
mainfrom
fix-medium-severity-issues
Sep 14, 2026
Merged

mmmarinho merged 1 commit into
mainfrom
fix-medium-severity-issues

Conversation

@mmmarinho

Copy link
Copy Markdown
Owner

Follow-up to the HIGH-severity fixes. This PR addresses the remaining MEDIUM items found in the tutorial audit.

1. Update 11 stale distro links to Jazzy

The tutorial was updated to ROS 2 Jazzy, but 11 links still pointed at Humble/Foxy. Each target was
verified to resolve on the current Jazzy docs (via the ROS documentation and Tavily), including
several Jazzy reorganisations:

File Old (broken/old) → New (Jazzy)
parameters_and_launch.rst Understanding-ROS2-Parameters.html → …/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.html
parameters_and_launch.rst Launch-Main.html → Creating-Launch-Files.html (Launch-Main.html no longer exists on Jazzy)
parameters_and_launch.rst Concepts/Basic/About-Parameters.html (×2, humble→jazzy)
publishers_and_subscribers.rst Concepts.html#quick-overview-of-ros-2-concepts → Concepts/Basic.html (anchor removed on Jazzy)
publishers_and_subscribers.rst About-Quality-of-Service-Settings.html → Concepts/Intermediate/About-Quality-of-Service-Settings.html
create_interface_package.rst About-ROS-Interfaces.html#field-types → Concepts/Basic/About-Interfaces.html#field-types (anchor kept — verified present)
interfaces.rst About-ROS-Interfaces.html → Concepts/Basic/About-Interfaces.html
python_node_explained.rst rclpy/blob/humble/…/timer.hpp → rclpy/blob/jazzy/…/timer.hpp
python_node_explained.rst docs.ros2.org/foxy/api/rclpy/…/init_shutdown.html → docs.ros.org/en/jazzy/p/rclpy/api/execution_and_callbacks.html (the old docs.ros2.org/<distro>/api/ layout now 404s)
transformations/tf2.rst docs.ros2.org/foxy/api/tf2_ros/…Buffer.html → docs.ros.org/en/jazzy/p/tf2_ros/generated/classtf2__ros_1_1Buffer.html

Note: the ros2-tutorial.readthedocs.io/en/humble/… "previous version" links (in service_servers_and_clients.rst and create_interface_package.rst) are intentional and were left unchanged.

2. Make the Gazebo "other content" page reachable

docs/source/gazebo/other_content.rst (the Gazebo and ROS2 structure sensor/topic table + entities
examples) was not in any toctree, so it was unreachable. Added gazebo/other_content to the Gazebo
toctree in docs/source/index.rst.

3. Remove three dead RST files

None of these were referenced (no toctree, :doc:, :ref:, include, or literalinclude), so
Sphinx never built them:

  • docker/troubleshooting.rst — its content is already inlined under Tips and troubleshooting in docker/index.rst.
  • the_pycharm_dependencies_warning.rst — orphaned reusable snippet and it contained a dangling :ref: (PyCharm is not finding the dependencies, a label defined nowhere).
  • the_section_is_optional.rst — orphaned reusable snippet.

All changes are documentation-only; CI (colcon build) is unaffected.


Created by an AI agent (OpenHands) on behalf of the user.

- 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/<distro>/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 <openhands@all-hands.dev>

@mmmarinho mmmarinho left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

@mmmarinho
mmmarinho merged commit 9627b49 into main Sep 14, 2026
4 checks passed
@mmmarinho
mmmarinho deleted the fix-medium-severity-issues branch September 14, 2026 22:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant