[3di-for-openrobotics]

Description

This article is a brief, high-level overview of how the elements of the ROS framework interact. This article is not meant to be in-depth but, rather, to help a beginner to understand how a ROS system is constructed and direct the them to other articles to learn more about each element.

Fixes #6826

Did you use Generative AI?

Yes, GPT-5 for the FAQ section.

Additional Information

Documentation updates from 3di Information Solutions, agreed with Geoff and Tully.

Label

Please add backport-lyrical.

[ahcorde]

1. CI failure (source/ROS-Framework/How-ROS-Works.rst:125): trailing whitespace on lines 12, 42, 53, 72 and 102, plus a missing final newline, gives 6 doc8 errors. This fails the make test step.
2. Wrong link target (How-ROS-Works.rst:88): the link for the user-facing ROS API goes to About-Internal-Interfaces, an expert page that says those interfaces aren't meant for typical users. It should point to About-Client-Libraries.
3. Misleading parameter wording (How-ROS-Works.rst:48): "can be modified during runtime if your code allows it" suggests you have to opt in. Runtime changes are normal unless blocked by a read-only descriptor or a rejecting callback, so a reader could leave a parameter unprotected.
4. Diagram hides request/response (How-ROS-Works.rst:68): services and actions use the same one-way arrows as topics. Use bidirectional arrows or client/server labels.
5. Incomplete command list (Understanding-ROS2-Nodes.rst:33): the Summary presents the commands used in the tutorial but leaves out ros2 node info and ros2 run turtlesim turtle_teleop_key. Step 3 teaches ros2 node info.
6. Link label and path (Understanding-ROS2-Nodes.rst:41): the "ROS Graph" link lands on the page titled "How ROS works". Its path also uses ../../../../ROS-Framework/, while the rest of the file uses ../../../.
7. Empty toctree (How-ROS-Works.rst:19): removing the entries leaves a hidden toctree with nothing in it, so the block should be deleted.
8. How-ROS-Works.rst:125: "visualised" should be "visualized"