Added documentation for code generation

Signed-off-by: Gonzalo de Pedro <[email protected]>

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.
+-  ``Client`` 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.
+
+*Client* 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 *Client* 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 *client* 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