docs: Enhance ROS 2 documentation clarity and consistency (Issue #1487)

.gitignore

@@ -4,3 +4,9 @@ _build/
 .vscode/
 __pycache__
 ros2doc/
+
+# --- AI Bot Generated Ignores (DO NOT MANUALLY EDIT BELOW THIS LINE) ---
+*.exe
+*.so
+.venv
+.venv/

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

@@ -53,7 +53,7 @@ The ``rclpy`` package
 The ROS Client Library for Python (``rclpy``) is the Python counterpart to the C++ client library.
 Like the C++ client library, ``rclpy`` also builds on top of the ``rcl`` C API for its implementation.
 The interface provides an idiomatic Python experience that uses native Python types and patterns like lists and context objects.
-By using the ``rcl`` |API| in the implementation, it stays consistent with the other client libraries in terms of feature parity and behavior.
+Using the ``rcl`` |API| helps maintain consistency with the other client libraries in terms of feature parity and behavior.
 In addition to providing Python idiomatic bindings around the ``rcl`` |API| and Python classes for each message, the Python client library takes care of the execution model, using ``threading.Thread`` or similar to run the functions in the ``rcl`` |API|.
 
 Like C++ it generates custom Python code for each ROS message that the user interacts with, but unlike C++ it eventually converts the native Python message object into the C version of the message.

source/Concepts/Intermediate/About-Composition.rst

@@ -88,14 +88,18 @@ Using Components
 ----------------
 
 The `composition <https://github.com/ros2/demos/tree/{REPOS_FILE_BRANCH}/composition>`__ package contains a couple of different approaches on how to use components.
-The three most common ones are:
-
-#. Start a (`generic container process <https://github.com/ros2/rclcpp/blob/{REPOS_FILE_BRANCH}/rclcpp_components/src/component_container.cpp>`__) and call the ROS service `load_node <https://github.com/ros2/rcl_interfaces/blob/{REPOS_FILE_BRANCH}/composition_interfaces/srv/LoadNode.srv>`__ offered by the container.
-   The ROS service will then load the component specified by the passed package name and library name and start executing it within the running process.
-   Instead of calling the ROS service programmatically you can also use a `command line tool <https://github.com/ros2/ros2cli/tree/{REPOS_FILE_BRANCH}/ros2component>`__ to invoke the ROS service with the passed command line arguments
-#. Create a `custom executable <https://github.com/ros2/demos/blob/{REPOS_FILE_BRANCH}/composition/src/manual_composition.cpp>`__ containing multiple nodes which are known at compile time.
-   This approach requires that each component has a header file (which is not strictly needed for the first case).
-#. Create a launch file and use ``ros2 launch`` to create a container process with multiple components loaded.
+The composition can occur at:
+
+* **Compile time**: Create a `custom executable <https://github.com/ros2/demos/blob/{REPOS_FILE_BRANCH}/composition/src/manual_composition.cpp>`__ containing multiple nodes which are known at compile time.
+ This approach requires that each component has a header file (which is not strictly needed for the other cases).
+
+* **Launch time**: Create a launch file and use ``ros2 launch`` to start a container process and load multiple components into it.
+ This often uses the underlying service call mechanism described below.
+ See the :doc:`launching composable nodes <../../How-To-Guides/Launching-composable-nodes>` how-to guide for examples.
+
+* **Run time**: Start a (`generic container process <https://github.com/ros2/rclcpp/blob/{REPOS_FILE_BRANCH}/rclcpp_components/src/component_container.cpp>`__) and then call the ROS service `load_node <https://github.com/ros2/rcl_interfaces/blob/{REPOS_FILE_BRANCH}/composition_interfaces/srv/LoadNode.srv>`__ offered by the container.
+ The ROS service will then load the component specified by the passed package name and library name and start executing it within the running process.
+ Instead of calling the ROS service programmatically you can also use the `ros2 component load <https://github.com/ros2/ros2cli/tree/{REPOS_FILE_BRANCH}/ros2component>`__ command line tool to invoke the ROS service with the passed command line arguments.
 
 Practical application
 ---------------------

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

@@ -81,7 +81,7 @@ Here is a list of inter-vendor communication configurations that are not support
 Default RMW implementation
 --------------------------
 
-If a ROS 2 workspace has multiple RMW implementations, Fast DDS is selected as the default RMW implementation if it is available.
+Fast DDS is the default RMW implementation.
 If the Fast DDS RMW implementation is not installed, the RMW implementation with the first RMW implementation identifier in alphabetical order will be used.
 The implementation identifier is the name of the ROS package that provides the RMW implementation, e.g. ``rmw_cyclonedds_cpp``.
 For example, if both ``rmw_cyclonedds_cpp`` and ``rmw_connextdds`` ROS packages are installed, ``rmw_connextdds`` would be the default.

source/How-To-Guides/Developing-a-ROS-2-Package.rst

@@ -32,7 +32,7 @@ All ROS 2 packages begin by running the command
 
    $ ros2 pkg create --license Apache-2.0 <pkg-name> --dependencies [deps]
 
-in your workspace (usually ``~/ros2_ws/src``).
+in your workspace (e.g., ``~/your_project_ws/src``).
 
 To create a package for a specific client library:
 
@@ -62,6 +62,7 @@ You will mostly use the ``add_executable()`` CMake macro along with
    target_link_libraries(<executable-name> PUBLIC [targets from your dependencies])
 
 to create executable nodes and link dependencies.
+CMake, when used with `ament_target_dependencies` or similar functions, also automatically manages the necessary include directories for your targets.
 
 To install your launch files and nodes, you can use the ``install()`` macro placed towards the end of the file but before the ``ament_package()`` macro.
 

source/How-To-Guides/Installation-Troubleshooting.rst

@@ -43,15 +43,19 @@ If the first command did not return a response similar to:
 
    Received from xx.xxx.xxx.xx:43751: 'Hello World!'
 
-then you will need to update your firewall configuration to allow multicast using `ufw <https://help.ubuntu.com/community/UFW>`__.
+then multicast may not be enabled or properly configured on your system.
+
+If the general multicast check fails, you may need to update your firewall configuration.
+This is especially common on Linux systems where you can use `ufw <https://help.ubuntu.com/community/UFW>`__ to allow multicast.
 
 .. code-block:: console
 
    $ sudo ufw allow in proto udp to 224.0.0.0/4
    $ sudo ufw allow in proto udp from 224.0.0.0/4
 
 
-You can check if the multicast flag is enabled for your network interface using the :code:`ifconfig` tool and looking for :code:`MULTICAST` in the flags section:
+You can check if the multicast flag is enabled for your network interface using the :code:`ifconfig` tool.
+Look for :code:`MULTICAST` in the flags section:
 
 .. code-block:: bash
 
@@ -247,6 +251,7 @@ To resolve this error, you will need to:
 
 rosdep install error ``homebrew: Failed to detect successful installation of [qt5]``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 While following the :doc:`Creating a workspace <../Tutorials/Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace>` tutorial, you might encounter the following error stating that ``rosdep`` fails to install Qt5.
 
 .. code-block:: console

source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst

@@ -22,8 +22,9 @@ Background
 
 ROS 2 relies on the notion of combining workspaces using the shell environment.
 "Workspace" is a ROS term for the location on your system where you're developing with ROS 2.
-The core ROS 2 workspace is called the underlay.
-Subsequent local workspaces are called overlays.
+Workspaces are often layered on top of each other.
+When viewing one workspace in relation to another, the base workspace it extends is often called the 'underlay', and the subsequent workspace currently being used or developed is called the 'overlay'.
+These terms are relative; a workspace could be an overlay relative to the core ROS 2 installation, but an underlay relative to a newer local workspace you create.
 When developing with ROS 2, you will typically have several workspaces active concurrently.
 
 Combining workspaces makes developing against different versions of ROS 2, or against different sets of packages, easier.

source/index.rst

@@ -12,9 +12,9 @@ ROS 2 Documentation
 
    Installation
    Releases
+   Concepts
    Tutorials
    How-To-Guides
-   Concepts
    Contact
    The-ROS2-Project
    Package-Docs
@@ -27,7 +27,7 @@ ROS 2 Documentation
 From drivers and state-of-the-art algorithms to powerful developer tools, ROS has the open source tools you need for your next robotics project.
 
 Since ROS was started in 2007, a lot has changed in the robotics and ROS community.
-The goal of the ROS 2 project is to adapt to these changes, leveraging what is great about ROS 1 and improving what isn't.
+The goal of the ROS 2 project is to adapt to these changes, leveraging what is great about ROS 1 and improving what isn\'t.
 
 **Are you looking for documentation for a particular ROS package like MoveIt, image_proc, or octomap?**
 Please see `ROS Index <https://index.ros.org/?search_packages=true#{DISTRO}>`__ or check out `this index of per-package documentation <https://docs.ros.org/en/{DISTRO}/p/>`__.
@@ -44,6 +44,10 @@ Getting started
 
   - Instructions to set up ROS 2 for the first time
 
+* :doc:`Concepts <Concepts>`
+
+  - High-level explanations of core ROS 2 concepts covered in the :doc:`Tutorials <Tutorials>`
+
 * :doc:`Tutorials <Tutorials>`
 
   - The best place to start for new users!
@@ -54,10 +58,6 @@ Getting started
   - Quick answers to your "How do I...?"
     questions without working through the :doc:`Tutorials <Tutorials>`
 
-* :doc:`Concepts <Concepts>`
-
-  - High-level explanations of core ROS 2 concepts covered in the :doc:`Tutorials <Tutorials>`
-
 * :doc:`Contact <Contact>`
 
   - Answers to your questions or a forum to start a discussion
@@ -66,11 +66,14 @@ Getting started
 The ROS 2 project
 -----------------
 
-If you're interested in the advancement of the ROS 2 project:
+Information about the ROS 2 project:
 
 * :doc:`Contributing <The-ROS2-Project/Contributing>`
 
-  - Best practices and methodology for contributing to ROS 2, as well as instructions for migrating existing ROS 1 content to ROS 2
+  - Best practices and methodology for contributing to ROS 2 (including code, documentation, and other content), as well as instructions for migrating existing ROS 1 content to ROS 2
+
+Development and Status
+~~~~~~~~~~~~~~~~~~~~~~
 
 * :doc:`Distributions <Releases>`
 
@@ -92,6 +95,9 @@ If you're interested in the advancement of the ROS 2 project:
 
   - Presentations by the community on ROS 2
 
+Governance and Marketing
+~~~~~~~~~~~~~~~~~~~~~~~~
+
 * :doc:`Project Governance <The-ROS2-Project/Governance>`
 
   - Information about the ROS Technical Steering Committee, Working Groups, and upcoming events
@@ -121,8 +127,8 @@ If you need help, have an idea, or would like to contribute to the project, plea
 
   - Indexed list of all packages (i.e. `Python Package Index (PyPI) <https://pypi.org/>`_ for ROS packages)
   - See which ROS distributions a package supports
-  - Link to a package's repository, API documentation, or website
-  - Inspect a package's license, build type, maintainers, status, and dependencies
+  - Link to a package\'s repository, API documentation, or website
+  - Inspect a package\'s license, build type, maintainers, status, and dependencies
   - Get more info for a package on `Robotics Stack Exchange <https://robotics.stackexchange.com/>`__
 
 * `ROS resource status page <https://status.openrobotics.org/>`__ (ROS 1, ROS 2)