Code generation documentation

.gitignore

@@ -1,5 +1,5 @@
 build/
-plugins/__pycache__
 _build/
 .idea/
 .vscode/
+__pycache__

.mergify.yml

@@ -2,7 +2,7 @@ pull_request_rules:
   - name: automatic backport of common pages
     conditions:
       - base=rolling
-      - "files~=Governance|Contact|index|Marketing|ROSCon-Content|Roadmap|Releases|Feature-Ideas"
+      - "files~=Governance|Contact|index|Marketing|ROSCon-Content|Roadmap|Releases|Feature-Ideas|Metrics"
     actions:
       backport:
         branches:

README.md

@@ -11,3 +11,43 @@ Please see the [Contributing to ROS 2 Documentation](https://docs.ros.org/en/rol
 ## Contributing to ROS 2
 
 To contribute to the ROS 2 source code project please refer to the [ROS 2 contributing guidelines](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing.html).
+
+## Prerequisites
+
+To build this you need to install
+
+* make
+* graphviz
+* python virtualenv
+
+
+In the virtualenv 
+
+```
+pip install -r requirements.txt -c constraints.txt
+```
+
+### Pinned versions
+
+For development we currently use Jammy as our build platform.
+And all python versions are pinned in the constraints file to make sure that things are reproducible.
+To upgrade the system validate that things are working and then use `pip freeze > constraints.txt` to lock in the versions to upgrade.
+
+## Building HTML
+
+### Local development test
+For local testing of the current tree use:
+
+`make html`
+
+`sensible-browser build/html/index.html`
+
+### Deployment test
+
+To test building the multisite version deployed to the website use:
+
+`make multiversion`
+
+`sensible-browser build/html/rolling/index.html`
+
+**NB:** This will ignore local workspace changes and build from the branches.

conf.py

@@ -83,6 +83,7 @@
     'sphinx_tabs.tabs',
     'sphinx_rtd_theme',
     'sphinx_sitemap_ros',
+    'sphinxcontrib.mermaid',
 ]
 
 # Intersphinx mapping

constraints.txt

@@ -1,35 +1,33 @@
-Jinja2==3.0.3
-MarkupSafe==2.0.1
-Pygments==2.11.2
 alabaster==0.7.12
-babel==2.8.0
+Babel==2.14.0
 certifi==2020.6.20
 chardet==4.0.0
+doc8==1.1.1
+docutils==0.20.1
+idna==2.10
 imagesize==1.3.0
-importlib-metadata==4.6.4
-more-itertools==8.10.0
+Jinja2==3.0.3
+MarkupSafe==2.0.1
 packaging==21.3
 pbr==5.8.0
-pip==22.0.2
+Pygments==2.17.2
 pyparsing==2.4.7
 pytz==2022.1
 requests==2.25.1
-restructuredtext-lint==1.3.2
-roman==3.3
-setuptools==59.6.0
-six==1.16.0
+restructuredtext_lint==1.3.2
 snowballstemmer==2.2.0
-Sphinx==4.3.2
-sphinx-copybutton==0.4.0
+Sphinx==7.2.6
+sphinx-copybutton==0.5.2
 sphinx-multiversion==0.2.4
-sphinx-rtd-theme==1.0.0
-sphinx-tabs==3.2.0
+sphinx-rtd-theme==2.0.0
+sphinx-tabs==3.4.5
 sphinxcontrib-applehelp==1.0.4
 sphinxcontrib-devhelp==1.0.2
 sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-mermaid==0.9.2
 sphinxcontrib-qthelp==1.0.3
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==1.1.10
 stevedore==3.5.0
 urllib3==1.26.5
-wheel==0.37.1
-zipp==1.0.0

docker/image/Dockerfile

@@ -16,13 +16,7 @@ RUN apt-get update && \
         git-all \
         graphviz \
         make \
-        python3-doc8 \
-        python3-docutils \
-        python3-pip \
-        python3-sphinx \
-        python3-sphinx-copybutton \
-        python3-sphinx-rtd-theme \
-        python3-sphinx-tabs && \
+        python3-pip && \
     rm -rf /var/lib/apt/lists/*
 
 RUN useradd -u $uid -m $user

requirements.txt

@@ -1,8 +1,9 @@
 doc8
 docutils
-pip==22.0.2
-sphinx==4.3.2
-sphinx-copybutton==0.4.0
-sphinx-multiversion==0.2.4
-sphinx-rtd-theme==1.0.0
-sphinx-tabs==3.2.0
+pip
+sphinx
+sphinx-copybutton
+sphinx-multiversion
+sphinx-rtd-theme
+sphinx-tabs
+sphinxcontrib-mermaid

source/Concepts/Advanced/About-Internal-Interfaces.rst

@@ -191,3 +191,58 @@ These are mainly used for error handling, commandline argument parsing, and logg
 The ``rcutils`` |API| and implementation are located in the `ros2/rcutils <https://github.com/ros2/rcutils>`_ repository on |GitHub|_ which contains the interface as C headers.
 
 For a complete definition of the ``rcutils`` |API|, see `the rcutils docs <https://docs.ros.org/en/{DISTRO}/p/rcutils/>`_.
+
+Automatic code generation using template files
+==============================================
+
+As mentioned above, in order to deal with different DDS implementations, code has to be generated. Code generation is handled by a clever usage
+of CMake and Ament. To simplify the explanation of this mechanism let's separate ROS2 projects that generate or need code to be generated in two types.
+
+-  ``Generator`` projects, which are the ones that have the templates and logic to generate code.
+-  ``Interface`` projects, which are the ones that need code to be generated, they have the parameters to generate code.
+
+For instance, typesupport packages that generate code for a particular dds implementation are *Generator* packages, same case that rosidl which
+generates code from ros idl (.msg, .action, etc) files.
+
+*Interface* projects are typically projects that define messages, actions and services. Which have .msg files with rosidl defined on them which are
+used by *Generator* projects to create code. A package that calls rosidl_generate_interfaces CMake macro is a *Interface* project.
+
+Code generation workflow
+------------------------
+
+On workspace build, the *generator* packages, registers a portion of CMake code as an ament_extension under 'rosidl_generate_idl_interfaces' key.
+
+Hook registration on CodeGenerator project build
+
+.. mermaid::
+
+    sequenceDiagram
+    participant CodeGenerator_cmake
+    participant ament_package
+    participant ament_register_extension
+    CodeGenerator_cmake->>ament_package: CONFIG_EXTRAS
+    ament_package->>ament_register_extension: rosidl_generate_idl_interfaces, cmake_code_hook
+    Note right of ament_package: Execute a cmake.in template with variables and a cmake code hook.
+
+
+When the *interface* package, during its build process, calls the 'rosidl_generate_interfaces' macro, the extensions that were registered for each of the
+*generator* packages, get called. Said extensions have the code to generate sources for each of the IDL interfaces. Then, code is added to an artifact
+(a library) and dependiences are exported for code to be build and installed.
+
+.. mermaid::
+
+    sequenceDiagram
+    participant project_with_rosidl_files
+    participant rosidl_generate_interfaces
+    participant rosidl_generate_idl_interfaces_HOOK
+    participant generate_arguments_file
+    participant rosidl_generator
+    project_with_rosidl_files->>rosidl_generate_interfaces: path_to_idl_files
+    loop ForEach Hook
+        rosidl_generate_interfaces->>rosidl_generate_idl_interfaces_HOOK: path_to_idl_files, parameters
+        rosidl_generate_idl_interfaces_HOOK->>generate_arguments_file: template_parameters
+        activate generate_arguments_file
+        generate_arguments_file->>rosidl_generate_idl_interfaces_HOOK: arguments_file
+        deactivate generate_arguments_file
+        rosidl_generate_idl_interfaces_HOOK->>rosidl_generator: arguments_file
+    end

source/The-ROS2-Project.rst

@@ -13,3 +13,4 @@ Check out the resources below to learn more about the advancement of the ROS 2 p
    The-ROS2-Project/ROSCon-Content
    The-ROS2-Project/Governance
    The-ROS2-Project/Marketing
+   The-ROS2-Project/Metrics

source/The-ROS2-Project/Metrics.rst

@@ -0,0 +1,44 @@
+.. _Metrics:
+
+Metrics
+=======
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+
+We measure aspects of the ROS community to understand and track the impact of our work and identify areas for improvement.
+We take inspiration from the MeeGo Project's metrics.
+
+Metrics.ros.org
+---------------
+
+At `metrics.ros.org <https://metrics.ros.org>`_ you can find many visualizations of metrics about ROS.
+
+Periodic Metrics Report
+-----------------------
+
+We periodically publish a metrics report that provides a quantitative view of the ROS community.
+We're collectively learning what to measure and how and evoloving as systems change.
+Please provide feedback!
+Add your suggestions on how to improve these reports by posting them to `ROS Discourse Site Feedback Category <http://discourse.ros.org/c/site-feedback>`_.
+
+Historical Metrics Reports
+..........................
+
+* :download:`2023 <http://download.ros.org/downloads/metrics/metrics-report-2024-01.pdf>`
+* :download:`2022 <http://download.ros.org/downloads/metrics/metrics-report-2022-07.pdf>`
+* :download:`2021 <http://download.ros.org/downloads/metrics/metrics-report-2021-07.pdf>`
+* :download:`2020 <http://download.ros.org/downloads/metrics/metrics-report-2020-07.pdf>`
+* :download:`2019 <http://download.ros.org/downloads/metrics/metrics-report-2019-07.pdf>`
+* :download:`2018 <http://download.ros.org/downloads/metrics/metrics-report-2018-07.pdf>`
+* :download:`2017 <http://download.ros.org/downloads/metrics/metrics-report-2017-07.pdf>`
+* :download:`2016 <http://download.ros.org/downloads/metrics/metrics-report-2016-07.pdf>`
+* :download:`2015 <http://download.ros.org/downloads/metrics/metrics-report-2015-07.pdf>`
+* :download:`2014 <http://download.ros.org/downloads/metrics/metrics-report-2014-07.pdf>`
+* :download:`2013 <http://download.ros.org/downloads/metrics/metrics-report-2013-08.pdf>`
+* :download:`2012 <http://download.ros.org/downloads/metrics/metrics-report-2012-07.pdf>`
+* :download:`2011 <http://download.ros.org/downloads/metrics/metrics-report-2011-08.pdf>`
+
+

source/Tutorials/Advanced/Simulators/Webots/Setting-Up-Simulation-Webots-Advanced.rst

@@ -151,11 +151,10 @@ You have to modify these two other files to launch your new node.
             :language: cmake
 
 
-Go to the file ``robot_launch.py`` and replace ``def generate_launch_description():`` with:
+Go to the file ``robot_launch.py`` and replace it with:
 
 .. literalinclude:: Code/robot_launch_sensor.py
     :language: python
-    :lines: 10-40
 
 This will create an ``obstacle_avoider`` node that will be included in the ``LaunchDescription``.
 

source/Tutorials/Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace.rst

@@ -38,7 +38,7 @@ Prerequisites
 * `git installation <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`__
 * :doc:`turtlesim installation <../../Beginner-CLI-Tools/Introducing-Turtlesim/Introducing-Turtlesim>`
 * Have :doc:`rosdep installed <../../Intermediate/Rosdep>`
-* Understanding of basic terminal commands (`here's a guide for Linux <http://www.ee.surrey.ac.uk/Teaching/Unix/>`__)
+* Understanding of basic terminal commands (`here's a guide for Linux <https://www2.cs.sfu.ca/~ggbaker/reference/unix/>`__)
 * Text editor of your choice
 
 Tasks