Documentation changes propagation to Iron (#19)

* Fix reference warnings (#4) (#5) * Fix reference warnings Signed-off-by: RaulSanchez <raul@eprosima.com> * Change absolute paths by relative paths in internal links Signed-off-by: RaulSanchez <raul@eprosima.com> Signed-off-by: RaulSanchez <raul@eprosima.com> (cherry picked from commit 428aa83) Co-authored-by: Raul Sanchez-Mateos Lizano <raul@eprosima.com> * Fix reference warning in ROS 2 releases Signed-off-by: RaulSanchez <raul@eprosima.com> * Add references for micro-ROS tutorials (#6) * Add sections marks Signed-off-by: acuadros95 <acuadros1995@gmail.com> * Apply suggestions from code review Co-authored-by: Eduardo Ponz Segrelles <eduardoponz@eprosima.com> Signed-off-by: acuadros95 <acuadros1995@gmail.com> Co-authored-by: Pablo Garrido <pablogs9@gmail.com> Co-authored-by: Eduardo Ponz Segrelles <eduardoponz@eprosima.com> * Add reference to Field Types section (#9) Signed-off-by: Eduardo Ponz <eduardoponz@eprosima.com> Signed-off-by: Eduardo Ponz <eduardoponz@eprosima.com> * A references for Parameters tutorial and DDS vendors section (#11) * sphinx references Signed-off-by: Mikel Rico <mikelrico@eprosima.com> * sphinx references Signed-off-by: Mikel Rico <mikelrico@eprosima.com> Signed-off-by: Mikel Rico <mikelrico@eprosima.com> * Add label to discovery server tutorial (#13) Signed-off-by: JLBuenoLopez-eProsima <joseluisbueno@eprosima.com> Signed-off-by: JLBuenoLopez-eProsima <joseluisbueno@eprosima.com> * Add label to Fast DDS tutorial in ROS 2 documentation (#15) Signed-off-by: JLBuenoLopez-eProsima <joseluisbueno@eprosima.com> * Fixed typos (#18) Signed-off-by: Javier Santiago <javiersantiago@eprosima.com> --------- Signed-off-by: RaulSanchez <raul@eprosima.com> Signed-off-by: acuadros95 <acuadros1995@gmail.com> Signed-off-by: Eduardo Ponz <eduardoponz@eprosima.com> Signed-off-by: Mikel Rico <mikelrico@eprosima.com> Signed-off-by: JLBuenoLopez-eProsima <joseluisbueno@eprosima.com> Signed-off-by: Javier Santiago <javiersantiago@eprosima.com> Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> Co-authored-by: Raul Sanchez-Mateos Lizano <raul@eprosima.com> Co-authored-by: Antonio Cuadros <49162117+Acuadros95@users.noreply.github.com> Co-authored-by: Pablo Garrido <pablogs9@gmail.com> Co-authored-by: Eduardo Ponz Segrelles <eduardoponz@eprosima.com> Co-authored-by: MRicoIE2C <43696963+MRicoIE2C@users.noreply.github.com> Co-authored-by: José Luis Bueno López <69244257+JLBuenoLopez-eProsima@users.noreply.github.com>
eProsima · Jul 20, 2023 · 535aa87 · 535aa87
1 parent c37221c
commit 535aa87
Show file tree

Hide file tree

Showing 20 changed files with 140 additions and 34 deletions.
diff --git a/source/Concepts.rst b/source/Concepts.rst
@@ -6,9 +6,112 @@ Conceptual overviews provide relatively high-level, general background informati
 .. toctree::
    :maxdepth: 1
 
-   Concepts/Basic
-   Concepts/Intermediate
-   Concepts/Advanced
+   Concepts/About-Domain-ID
+   Concepts/About-Different-Middleware-Vendors
+   Concepts/About-Logging
+   Concepts/About-Quality-of-Service-Settings
+   Concepts/About-ROS-2-Client-Libraries
+   Concepts/About-ROS-Interfaces
+   Concepts/About-ROS-2-Parameters
+   Concepts/About-Executors
+   Concepts/About-Topic-Statistics
+   Concepts/About-Command-Line-Tools
+   Concepts/About-RQt
+   Concepts/About-Composition
+   Concepts/About-Catment
+   Concepts/About-Cross-Compilation
+   Concepts/About-Security
+   Concepts/About-Tf2
+
+
+The Core Stack Developer Concepts are much more detailed conceptual articles intended for developers who plan modify or contribute to the ROS 2 core:
+
+.. toctree::
+  :maxdepth: 2
+
+  Concepts/About-Build-System
+  Concepts/About-Internal-Interfaces
+  Concepts/About-Middleware-Implementations
+
+Quick overview of ROS 2 Concepts
+--------------------------------
+
+.. contents::
+   :local:
+
+ROS 2 is a middleware based on an anonymous publish/subscribe mechanism that allows for message passing between different ROS processes.
+
+At the heart of any ROS 2 system is the ROS graph.
+The ROS graph refers to the network of nodes in a ROS system and the connections between them by which they communicate.
+
+Graph Concepts
+^^^^^^^^^^^^^^
+
+
+* Nodes: A node is an entity that uses ROS to communicate with other nodes.
+* Messages: ROS data type used when subscribing or publishing to a topic.
+* Topics: Nodes can publish messages to a topic as well as subscribe to a topic to receive messages.
+* Discovery: The automatic process through which nodes determine how to talk to each other.
+
+Nodes
+^^^^^
+
+A node is a participant in the ROS graph.
+ROS nodes use a ROS client library to communicate with other nodes.
+Nodes can publish or subscribe to Topics.
+Nodes can also provide or use Services and Actions.
+There are configurable Parameters associated with a node.
+Connections between nodes are established through a distributed discovery process.
+Nodes may be located in the same process, in different processes, or on different machines.
+These concepts will be described in more detail in the sections that follow.
+
+Client Libraries
+^^^^^^^^^^^^^^^^
+
+ROS client libraries allow nodes written in different programming languages to communicate.
+There is a core ROS client library (RCL) that implements common functionality needed for the ROS APIs of different languages.
+This makes it so that language-specific client libraries are easier to write and that they have more consistent behavior.
+
+The following client libraries are maintained by the ROS 2 team:
+
+
+* rclcpp = C++ client library
+* rclpy = Python client library
+
+Additionally, other client libraries have been developed by the ROS community.
+See the :doc:`ROS 2 Client Libraries <Concepts/About-ROS-2-Client-Libraries>` article for more details.
+
+Discovery
+^^^^^^^^^
+
+Discovery of nodes happens automatically through the underlying middleware of ROS 2.
+It can be summarized as follows:
+
+#. When a node is started, it advertises its presence to other nodes on the network with the same ROS domain (set with the ROS_DOMAIN_ID environment variable).
+   Nodes respond to this advertisement with information about themselves so that the appropriate connections can be made and the nodes can communicate.
+#. Nodes periodically advertise their presence so that connections can be made with new-found entities, even after the initial discovery period.
+#. Nodes advertise to other nodes when they go offline.
+
+Nodes will only establish connections with other nodes if they have compatible :doc:`Quality of Service <./Tutorials>` settings.
+
+Take the :ref:`talker-listener demo <talker-listener>` for example.
+Running the C++ talker node in one terminal will publish messages on a topic,
+and the Python listener node running in another terminal  will subscribe to messages on the same topic.
+
+You should see that these nodes discover each other automatically, and begin to exchange messages.
+
+Security
+^^^^^^^^
+
+ROS 2 includes the ability to secure communications among nodes within the ROS 2 computational graph.
+Similar to discovery, security happens through the underlying ROS 2 middleware (provided it has support for the corresponding security plugins).
+No additional software installation is needed to enable security; however, the middleware requires configuration files for each ROS graph participant.
+These files enable encryption and authentication, and define policies both for individual nodes and for the overall ROS graph.
+ROS 2 also adds a master "on/off" switch to control security behavior.
+
+ROS utilities can create the authoritative `trust anchor <https://en.wikipedia.org/wiki/Trust_anchor>`_ for a ROS application, or an external certificate authority can be used.
+
+See the :doc:`ROS 2 Security <Concepts/About-Security>` article for additional details or ROS security features.
 
 
 Related Content

diff --git a/source/Concepts/Basic/About-Interfaces.rst b/source/Concepts/Basic/About-Interfaces.rst
@@ -51,6 +51,8 @@ For example:
    int32 my_int
    string my_string
 
+.. _message_descriptions_field_types:
+
 Field types
 ~~~~~~~~~~~
 

diff --git a/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst b/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst
@@ -3,8 +3,10 @@
     DDS-and-ROS-middleware-implementations
     Concepts/About-Different-Middleware-Vendors
 
-Different ROS 2 middleware vendors
-==================================
+About different ROS 2 DDS/RTPS vendors
+======================================
+
+.. _concepts_ros2_vendors:
 
 .. contents:: Table of Contents
    :local:

diff --git a/source/Concepts/Intermediate/About-Domain-ID.rst b/source/Concepts/Intermediate/About-Domain-ID.rst
@@ -2,6 +2,8 @@
 
    Concepts/About-Domain-ID
 
+.. _concepts_domain_id_ros_domain_id:
+
 The ROS_DOMAIN_ID
 =================
 

diff --git a/source/Concepts/Intermediate/About-Quality-of-Service-Settings.rst b/source/Concepts/Intermediate/About-Quality-of-Service-Settings.rst
@@ -3,8 +3,10 @@
     About-Quality-of-Service-Settings
     Concepts/About-Quality-of-Service-Settings
 
-Quality of Service settings
-===========================
+.. _concepts_about_qos:
+
+About Quality of Service settings
+=================================
 
 .. contents:: Table of Contents
    :local:

diff --git a/source/How-To-Guides/Developing-a-ROS-2-Package.rst b/source/How-To-Guides/Developing-a-ROS-2-Package.rst
@@ -17,7 +17,7 @@ It is intended for developers who want to learn how to create custom packages in
 Prerequisites
 -------------
 
-- :doc:`Install ROS <../../Installation>`
+- :doc:`Install ROS <../Installation>`
 
 - `Install colcon <https://colcon.readthedocs.io/en/released/user/installation.html>`__
 

diff --git a/source/How-To-Guides/Releasing/_Next-Steps.rst b/source/How-To-Guides/Releasing/_Next-Steps.rst
@@ -1,5 +1,5 @@
 Once your pull request has been submitted, usually within one or two days, one of the maintainers of rosdistro will review and merge your Pull Request.
-If your package build is successful, in 24-48 hours your packages will become available in the **ros-testing** repository, where you can :doc:`test your pre-release binaries <../../../Installation/Testing>`.
+If your package build is successful, in 24-48 hours your packages will become available in the **ros-testing** repository, where you can :doc:`test your pre-release binaries <../../Installation/Testing>`.
 
 Approximately every two to four weeks, the distribution's release manager manually synchronizes the contents of ros-testing into the main ROS repository.
 This is when your packages actually become available to the rest of the ROS community.

diff --git a/source/Installation/Alternatives/images/windows-vs-studio-install.png b/source/Installation/Alternatives/images/windows-vs-studio-install.png
diff --git a/source/Installation/Maintaining-a-Source-Checkout.rst b/source/Installation/Maintaining-a-Source-Checkout.rst
@@ -3,13 +3,6 @@
 Maintain source checkout
 ========================
 
-.. ifconfig:: smv_current_version != '' and smv_current_version != 'rolling'
-
-  .. note::
-
-     For instructions on maintaining a source checkout of the **latest development version** of ROS 2, refer to
-     `Maintaining a source checkout of ROS 2 Rolling <../../rolling/Installation/Maintaining-a-Source-Checkout.html>`__
-
 .. contents::
    :depth: 2
    :local:

diff --git a/source/Installation/RHEL-Install-RPMs.rst b/source/Installation/RHEL-Install-RPMs.rst
@@ -148,10 +148,9 @@ You should see the ``talker`` saying that it's ``Publishing`` messages and the `
 This verifies both the C++ and Python APIs are working properly.
 Hooray!
 
-Next steps
-----------
-
-Continue with the :doc:`tutorials and demos <../../Tutorials>` to configure your environment, create your own workspace and packages, and learn ROS 2 core concepts.
+Next steps after installing
+---------------------------
+Continue with the :doc:`tutorials and demos <../Tutorials>` to configure your environment, create your own workspace and packages, and learn ROS 2 core concepts.
 
 Troubleshoot
 ------------

diff --git a/source/Installation/Ubuntu-Install-Debians.rst b/source/Installation/Ubuntu-Install-Debians.rst
@@ -118,16 +118,15 @@ You should see the ``talker`` saying that it's ``Publishing`` messages and the `
 This verifies both the C++ and Python APIs are working properly.
 Hooray!
 
-Next steps
-----------
-
-Continue with the :doc:`tutorials and demos <../../Tutorials>` to configure your environment, create your own workspace and packages, and learn ROS 2 core concepts.
+Next steps after installing
+---------------------------
+Continue with the :doc:`tutorials and demos <../Tutorials>` to configure your environment, create your own workspace and packages, and learn ROS 2 core concepts.
 
 Use the ROS 1 bridge (optional)
 -------------------------------
 
 The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa.
-See the dedicated :doc:`document <../../How-To-Guides/Using-ros1_bridge-Jammy-upstream>` on how to build and use the ROS 1 bridge.
+See the dedicated :doc:`document <../How-To-Guides/Using-ros1_bridge-Jammy-upstream>` on how to build and use the ROS 1 bridge.
 
 Troubleshoot
 ------------

diff --git a/source/Installation/Windows-Install-Binary.rst b/source/Installation/Windows-Install-Binary.rst
@@ -76,10 +76,9 @@ This verifies both the C++ and Python APIs are working properly.
 Hooray!
 
 
-Next steps
-----------
-
-Continue with the :doc:`tutorials and demos <../../Tutorials>` to configure your environment, create your own workspace and packages, and learn ROS 2 core concepts.
+Next steps after installing
+---------------------------
+Continue with the :doc:`tutorials and demos <../Tutorials>` to configure your environment, create your own workspace and packages, and learn ROS 2 core concepts.
 
 Troubleshoot
 ------------

diff --git a/source/Installation/_Windows-Install-Prerequisites.rst b/source/Installation/_Windows-Install-Prerequisites.rst
@@ -63,7 +63,7 @@ Make sure that the Visual C++ features are installed.
 
 An easy way to make sure they're installed is to select the ``Desktop development with C++`` workflow during the install.
 
-   .. image:: /Installation/images/windows-vs-studio-install.png
+   .. image:: ./images/windows-vs-studio-install.png
 
 Make sure that no C++ CMake tools are installed by unselecting them in the list of components to be installed.
 

diff --git a/source/Releases.rst b/source/Releases.rst
@@ -181,4 +181,4 @@ As the name implies, Rolling is continuously updated and **can have in-place upd
 We recommend that most people use the most recent stable distribution instead (see :ref:`list_of_distributions`).
 
 Packages released into the Rolling distribution will be automatically released into future stable distributions of ROS 2.
-:doc:`Releasing a ROS 2 package <../How-To-Guides/Releasing/Releasing-a-Package>` into the Rolling distribution follows the same procedures as all other ROS 2 distributions.
+:doc:`Releasing a ROS 2 package <./How-To-Guides/Releasing/Releasing-a-Package>` into the Rolling distribution follows the same procedures as all other ROS 2 distributions.
diff --git a/source/The-ROS2-Project/Contributing.rst b/source/The-ROS2-Project/Contributing.rst
@@ -47,7 +47,7 @@ Discussions and support
 -----------------------
 
 Some of the easiest ways to contribute to ROS 2 involve engaging in community discussions and support.
-You can find more information on how to pitch in on the :doc:`Contact <../../Contact>` page.
+You can find more information on how to pitch in on the :doc:`Contact <../Contact>` page.
 
 Contributing code
 -----------------

diff --git a/source/Tutorials/Advanced/Discovery-Server/Discovery-Server.rst b/source/Tutorials/Advanced/Discovery-Server/Discovery-Server.rst
@@ -3,6 +3,8 @@
     Discovery-Server
     Tutorials/Discovery-Server/Discovery-Server
 
+.. _ros2-advanced-tutorial-fastdds-discovery-server:
+
 Using Fast DDS Discovery Server as discovery protocol [community-contributed]
 =============================================================================
 

diff --git a/source/Tutorials/Advanced/FastDDS-Configuration.rst b/source/Tutorials/Advanced/FastDDS-Configuration.rst
@@ -37,6 +37,7 @@ This tutorial assumes that you know how to :doc:`create a package <../Beginner-C
 It also assumes you know how to write a :doc:`simple publisher and subscriber<../Beginner-Client-Libraries/Writing-A-Simple-Cpp-Publisher-And-Subscriber>` and a :doc:`simple service and client <../Beginner-Client-Libraries/Writing-A-Simple-Cpp-Service-And-Client>`.
 Although the examples are implemented in C++, the same concepts apply to Python packages.
 
+.. _ros2_tutorials_fastdds_sync_async:
 
 Mixing synchronous and asynchronous publications in the same node
 -----------------------------------------------------------------

diff --git a/source/Tutorials/Advanced/Security/Deployment-Guidelines.rst b/source/Tutorials/Advanced/Security/Deployment-Guidelines.rst
@@ -124,7 +124,7 @@ Now, build the docker image with the command:
 Understanding the compose file
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-A compose configration file takes an image to create containers as services.
+A compose configuration file takes an image to create containers as services.
 In this tutorial, three services are defined within the configuration:
 
 * *keystore-creator*: That, similarly to previous tutorials, it internally initializes a new keystore tree directory.

diff --git a/source/Tutorials/Advanced/Simulators/Gazebo/Gazebo.rst b/source/Tutorials/Advanced/Simulators/Gazebo/Gazebo.rst
@@ -26,7 +26,7 @@ You have two options:
  - Install from deb packages. To check which versions are available from deb packages please check this `table <https://github.com/gazebosim/ros_ign>`__.
  - Compile from sources:
 
-   - :doc:`ROS 2 install instructions <../../../../Installation>`
+   - :doc:`ROS 2 install instructions <../../../Installation>`
    - `Gazebo install instructions <https://gazebosim.org/docs>`__
 
 Tasks

diff --git a/source/Tutorials/Intermediate/Monitoring-For-Parameter-Changes-CPP.rst b/source/Tutorials/Intermediate/Monitoring-For-Parameter-Changes-CPP.rst
@@ -2,6 +2,8 @@
 
     Tutorials/Monitoring-For-Parameter-Changes-CPP
 
+.. _intermediate_monitor_parameters:
+
 Monitoring for parameter changes (C++)
 ======================================