From a02c707d8a175290c13af02c6ecad6db59a7a389 Mon Sep 17 00:00:00 2001 From: Emilio Cuesta Date: Wed, 25 Mar 2026 14:38:19 +0100 Subject: [PATCH 01/10] Add first version of build with master fallback Signed-off-by: Emilio Cuesta --- docs/conf.py | 35 +++++++++++++++++++ docs/fastdds/discovery/discovery_server.rst | 2 +- docs/fastdds/discovery/static.rst | 2 +- .../includes/sum_and_next_steps.rst | 2 +- .../includes/sum_and_next_steps.rst | 2 +- docs/fastdds/rtps_layer/rtps_layer.rst | 2 +- .../access_control_plugin.rst | 8 ++--- .../transport/shared_memory/shared_memory.rst | 2 +- docs/fastdds/transport/tcp/tcp.rst | 2 +- .../use_cases/request_reply/request_reply.rst | 3 +- .../statistics_module/statistics_module.rst | 2 +- .../well_known_deployments.rst | 2 +- .../fastdds/use_cases/zero_copy/zero_copy.rst | 2 +- .../xml_configuration/making_xml_profiles.rst | 4 +-- .../includes/sum_and_next_steps.rst | 2 +- .../rpc_calculator_basic_app/includes/app.rst | 3 +- .../rpc_calculator_basic_app/intro.rst | 2 +- .../rpc_calculator_feed_app/includes/app.rst | 3 +- .../rpc_calculator_feed_app/intro.rst | 2 +- docs/fastddsgen/usage/usage.rst | 2 +- .../configuration/cmake_options.rst | 4 +-- docs/installation/sources/sources_linux.rst | 8 ++--- docs/installation/sources/sources_mac.rst | 4 +-- docs/installation/sources/sources_windows.rst | 8 ++--- docs/notes/migration_guide.rst | 2 +- docs/notes/notes.rst | 2 +- docs/notes/previous_versions/v2.6.10.rst | 2 +- docs/notes/previous_versions/v2.6.11.rst | 2 +- docs/notes/previous_versions/v2.6.9.rst | 2 +- docs/notes/previous_versions/v3.0.0.rst | 6 ++-- docs/notes/versions.rst | 6 ++-- 31 files changed, 81 insertions(+), 49 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5fb29d4481..7a2e6a2173 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -480,10 +480,34 @@ def configure_doxyfile( "sphinx_copybutton", "sphinx_design", "sphinx.ext.autodoc", # Document Pydoc documentation from Python bindings. + "sphinx.ext.extlinks", "sphinx_substitution_extensions", "sphinx_toolbox.collapse", ] +extlinks = { + # Fast-DDS repo (tree = directory, blob = file) + "fastdds-tree": ( + f"https://github.com/eProsima/Fast-DDS/tree/{fastdds_fallback_branch}/%s", "%s" + ), + "fastdds-blob": ( + f"https://github.com/eProsima/Fast-DDS/blob/{fastdds_fallback_branch}/%s", "%s" + ), + # Fast-DDS-python repo + "fastdds-python-tree": ( + f"https://github.com/eProsima/Fast-DDS-python/tree/{fastdds_python_branch}/%s", "%s" + ), + # Fast-DDS-docs repo (code examples embedded in the docs repo) + "fastdds-docs-tree": ( + f"https://github.com/eProsima/Fast-DDS-docs/tree/{fastdds_fallback_branch}/%s", "%s" + ), + # Fast-DDS-Gen raw files + "fastddsgen-raw": ( + f"https://raw.githubusercontent.com/eProsima/Fast-DDS-Gen/{fastdds_fallback_branch}/%s", + "%s", + ), +} + sphinx_tabs_disable_css_loading = False sphinx_tabs_disable_tab_closing = True @@ -549,6 +573,13 @@ def configure_doxyfile( # The full version, including alpha/beta/rc tags. release = "3.6.0" +# Branch used for all Fast-DDS / Fast-DDS-docs / Fast-DDS-Gen links. +# Change this when branching for a release (e.g. "3.2.x", "3.2.0"). +fastdds_fallback_branch = "master" + +# Branch used for Fast-DDS-python links (default branch is "main"). +fastdds_python_branch = "main" + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -684,6 +715,10 @@ def configure_doxyfile( Pro .. |ProjectVersion| replace:: {version} + +.. |FastDDSBranch| replace:: {fastdds_fallback_branch} + +.. |FastDDSPythonBranch| replace:: {fastdds_python_branch} """ diff --git a/docs/fastdds/discovery/discovery_server.rst b/docs/fastdds/discovery/discovery_server.rst index dfb5b9ae12..d2921899f4 100644 --- a/docs/fastdds/discovery/discovery_server.rst +++ b/docs/fastdds/discovery/discovery_server.rst @@ -315,7 +315,7 @@ Full example ^^^^^^^^^^^^ The following constitutes a full example on how to configure *server* and *client* both programmatically and using XML. -You may also have a look at the *eProsima Fast DDS* Github repository, which contains `an example `_ +You may also have a look at the *eProsima Fast DDS* Github repository, which contains :fastdds-tree:`an example ` similar to the one discussed in this section, as well as multiple other examples for different use cases. Server side setup diff --git a/docs/fastdds/discovery/static.rst b/docs/fastdds/discovery/static.rst index c17ffe2705..01bf7bae02 100644 --- a/docs/fastdds/discovery/static.rst +++ b/docs/fastdds/discovery/static.rst @@ -63,7 +63,7 @@ and DataReaders) must be statically specified, which is done using dedicated XML A |DomainParticipant| may load several of such configuration files so that the information about different entities can be contained in one file, or split into different files to keep it more organized. *Fast DDS* provides a -`Static Discovery example `_ +:fastdds-blob:`Static Discovery example ` that implements this EDP discovery protocol. The following table describes all the possible elements of a STATIC EDP XML configuration file. diff --git a/docs/fastdds/getting_started/simple_app/includes/sum_and_next_steps.rst b/docs/fastdds/getting_started/simple_app/includes/sum_and_next_steps.rst index fbc8297e8e..17387aeb2e 100644 --- a/docs/fastdds/getting_started/simple_app/includes/sum_and_next_steps.rst +++ b/docs/fastdds/getting_started/simple_app/includes/sum_and_next_steps.rst @@ -10,4 +10,4 @@ Next steps In the *eProsima Fast DDS* Github repository you will find more complex examples that implement DDS communication for a multitude of use cases and scenarios. You can find them -`here `_. +:fastdds-tree:`here `. diff --git a/docs/fastdds/getting_started/simple_python_app/includes/sum_and_next_steps.rst b/docs/fastdds/getting_started/simple_python_app/includes/sum_and_next_steps.rst index 7b066b5358..2e84d3acfb 100644 --- a/docs/fastdds/getting_started/simple_python_app/includes/sum_and_next_steps.rst +++ b/docs/fastdds/getting_started/simple_python_app/includes/sum_and_next_steps.rst @@ -9,4 +9,4 @@ Next steps In the *eProsima Fast DDS* Github repository you will find more complex examples that implement DDS communication for a multitude of use cases and scenarios. You can find them -`here `_. +:fastdds-python-tree:`here `. diff --git a/docs/fastdds/rtps_layer/rtps_layer.rst b/docs/fastdds/rtps_layer/rtps_layer.rst index 4a5cd66df0..37040820f9 100644 --- a/docs/fastdds/rtps_layer/rtps_layer.rst +++ b/docs/fastdds/rtps_layer/rtps_layer.rst @@ -41,7 +41,7 @@ explaining the new features it presents. We recommend you to look at the example describing how to use the RTPS layer that come with the distribution while reading this section. It is located in -`examples/cpp/rtps `_. +:fastdds-tree:`examples/cpp/rtps `. Managing the Participant ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/fastdds/security/access_control_plugin/access_control_plugin.rst b/docs/fastdds/security/access_control_plugin/access_control_plugin.rst index b3566ba426..4fb0d4ccd8 100644 --- a/docs/fastdds/security/access_control_plugin/access_control_plugin.rst +++ b/docs/fastdds/security/access_control_plugin/access_control_plugin.rst @@ -105,9 +105,9 @@ The following is an example of the Domain Governance XML file contents. :end-before: <--> :linenos: -The `Governance XSD file `_ and +The :fastdds-blob:`Governance XSD file ` and the -`Governance XML example `_ +:fastdds-blob:`Governance XML example ` can also be downloaded from the `eProsima Fast DDS Github repository `_. Domain Rules @@ -442,9 +442,9 @@ The following is an example of the DomainParticipant Permissions XML file conten :end-before: <--> :linenos: -The `Permissions XSD file `_ and +The :fastdds-blob:`Permissions XSD file ` and the -`Permissions XML example `_ +:fastdds-blob:`Permissions XML example ` can also be downloaded from the `eProsima Fast DDS Github repository `_. Grant Section diff --git a/docs/fastdds/transport/shared_memory/shared_memory.rst b/docs/fastdds/transport/shared_memory/shared_memory.rst index 84aa15dca2..083dde7d25 100644 --- a/docs/fastdds/transport/shared_memory/shared_memory.rst +++ b/docs/fastdds/transport/shared_memory/shared_memory.rst @@ -269,6 +269,6 @@ Delivery Mechanisms example --------------------------- A hello world example suitable for supported delivery mechanisms can be found in the -`delivery_mechanisms folder `_. +:fastdds-tree:`delivery_mechanisms folder `. It shows a publisher and a subscriber that communicate through the desired delivery mechanism (which can be set to shared memory only). diff --git a/docs/fastdds/transport/tcp/tcp.rst b/docs/fastdds/transport/tcp/tcp.rst index 181a264fae..90277b5f0e 100644 --- a/docs/fastdds/transport/tcp/tcp.rst +++ b/docs/fastdds/transport/tcp/tcp.rst @@ -461,6 +461,6 @@ Delivery Mechanisms example --------------------------- A hello world example suitable for supported delivery mechanisms can be found in the -`delivery_mechanisms folder `_. +:fastdds-tree:`delivery_mechanisms folder `. It shows a publisher and a subscriber that communicate through the desired delivery mechanism (which can be set to TCP only). diff --git a/docs/fastdds/use_cases/request_reply/request_reply.rst b/docs/fastdds/use_cases/request_reply/request_reply.rst index 9fe1509e7b..fb90d07274 100644 --- a/docs/fastdds/use_cases/request_reply/request_reply.rst +++ b/docs/fastdds/use_cases/request_reply/request_reply.rst @@ -49,7 +49,7 @@ The DDS communication schema will be: The key for making *Request-Reply* work is relating the Request with the Reply in the client's side. *Fast DDS* API provides |SampleIdentity-api| to achieve this. -A full example can be found in `Fast DDS repository`_. +A full example can be found in the :fastdds-tree:`Fast DDS repository `. Getting started --------------- @@ -147,4 +147,3 @@ For this the client application has to compare the stored |SampleIdentity-api| w :start-after: //REQUEST_REPLY_EXAMPLE_CLIENT_RECEIVE_REPLY :end-before: //! -.. _Fast DDS repository: https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/request_reply diff --git a/docs/fastdds/use_cases/statistics_module/statistics_module.rst b/docs/fastdds/use_cases/statistics_module/statistics_module.rst index 7c832c45aa..3a9da64df4 100644 --- a/docs/fastdds/use_cases/statistics_module/statistics_module.rst +++ b/docs/fastdds/use_cases/statistics_module/statistics_module.rst @@ -38,7 +38,7 @@ another application should be configured to subscribe to those topics. This application is a DDS standard application where the statistics DataReaders should be created. In order to create these statistics DataReaders, the user should follow the next steps: -* Using the `statistics IDL `_ +* Using the :fastdds-blob:`statistics IDL ` provided in the public API, generate the |TopicDataTypes-api| with :ref:`Fast DDS-Gen `. * Create the |DomainParticipant-api| and register the |TopicDataTypes-api| and the corresponding statistics diff --git a/docs/fastdds/use_cases/well_known_deployments/well_known_deployments.rst b/docs/fastdds/use_cases/well_known_deployments/well_known_deployments.rst index b641970451..61c7a6cad5 100644 --- a/docs/fastdds/use_cases/well_known_deployments/well_known_deployments.rst +++ b/docs/fastdds/use_cases/well_known_deployments/well_known_deployments.rst @@ -48,7 +48,7 @@ each other, so they can start sharing user data right away, avoiding the EDP pha A complete description of the feature can be found at :ref:`discovery_static`. There is also a fully functional hello world example implementing STATIC EDP in the -`examples/cpp/static_edp_discovery `_ +:fastdds-tree:`examples/cpp/static_edp_discovery ` folder. The following subsections present an example configuration where a Publisher in diff --git a/docs/fastdds/use_cases/zero_copy/zero_copy.rst b/docs/fastdds/use_cases/zero_copy/zero_copy.rst index d0287d77c2..6c232c47cc 100644 --- a/docs/fastdds/use_cases/zero_copy/zero_copy.rst +++ b/docs/fastdds/use_cases/zero_copy/zero_copy.rst @@ -164,6 +164,6 @@ Next steps ---------- A hello world example suitable for supported delivery mechanisms can be found in the -`delivery_mechanisms folder `_. +:fastdds-tree:`delivery_mechanisms folder `. It shows a publisher and a subscriber that communicate through the desired delivery mechanism. As long as it is zero-copy compatible, both intra-process and data-sharing delivery mechanisms are zero-copy if used. diff --git a/docs/fastdds/xml_configuration/making_xml_profiles.rst b/docs/fastdds/xml_configuration/making_xml_profiles.rst index 33fd7a8880..b73ba7e1b3 100644 --- a/docs/fastdds/xml_configuration/making_xml_profiles.rst +++ b/docs/fastdds/xml_configuration/making_xml_profiles.rst @@ -38,7 +38,7 @@ The following sections will show implementation examples for each of these profi The :ref:`examplexml` section shows an XML file with all the possible configurations and profile types. This example is useful as a quick reference to look for a particular property and how to use it. The - `Fast DDS XSD scheme `_ + :fastdds-blob:`Fast DDS XSD scheme ` can be used as a quick reference too. .. _loadingapplyingprofiles: @@ -218,6 +218,6 @@ It also gives the participant a name that mixes literal text with the content fr .. warning:: - The `Fast DDS XSD schema `_ + The :fastdds-blob:`Fast DDS XSD schema ` does not support the environment variables expansion feature, so validation of an XML file with environment variables expansion expressions will fail. diff --git a/docs/fastddsgen/pubsub_app/includes/sum_and_next_steps.rst b/docs/fastddsgen/pubsub_app/includes/sum_and_next_steps.rst index 2582884993..f523c7e344 100644 --- a/docs/fastddsgen/pubsub_app/includes/sum_and_next_steps.rst +++ b/docs/fastddsgen/pubsub_app/includes/sum_and_next_steps.rst @@ -5,6 +5,6 @@ In this tutorial, a publisher/subscriber DDS application using *Fast DDS-Gen* ha The tutorial also describes how to generate IDL files that contain the description of the Topic data type. To continue developing DDS applications please take a look at the -`eProsima Fast DDS examples on github `_ +:fastdds-tree:`eProsima Fast DDS examples on github ` for ideas on how to improve this basic application through different configuration options, and also for examples of advanced *Fast DDS* features. diff --git a/docs/fastddsgen/rpc_calculator_basic_app/includes/app.rst b/docs/fastddsgen/rpc_calculator_basic_app/includes/app.rst index 127e9c847d..9aeb364aab 100644 --- a/docs/fastddsgen/rpc_calculator_basic_app/includes/app.rst +++ b/docs/fastddsgen/rpc_calculator_basic_app/includes/app.rst @@ -91,8 +91,7 @@ by specifying the operation name and through the CLI, and the results will be printed on the screen after receiving the reply from the server. Create a ``CalculatorClient.cpp`` file with this -`content `_: +:fastdds-docs-tree:`content `: Examining the code """""""""""""""""" diff --git a/docs/fastddsgen/rpc_calculator_basic_app/intro.rst b/docs/fastddsgen/rpc_calculator_basic_app/intro.rst index 0d3f9b1005..48b001381b 100644 --- a/docs/fastddsgen/rpc_calculator_basic_app/intro.rst +++ b/docs/fastddsgen/rpc_calculator_basic_app/intro.rst @@ -20,7 +20,7 @@ to call asynchronously the following operations: * **representation_limits**: Returns the minimum and maximum representable values for a 32-bit integer. The entire example source code is available in this -`link `_ +:fastdds-docs-tree:`link ` .. include:: includes/background.rst .. include:: includes/prerequisites.rst diff --git a/docs/fastddsgen/rpc_calculator_feed_app/includes/app.rst b/docs/fastddsgen/rpc_calculator_feed_app/includes/app.rst index 1e029cc4bb..864f9a8221 100644 --- a/docs/fastddsgen/rpc_calculator_feed_app/includes/app.rst +++ b/docs/fastddsgen/rpc_calculator_feed_app/includes/app.rst @@ -27,8 +27,7 @@ Client application The client application extends the functionality of the basic example by adding the new operations defined in the IDL file. Create a ``CalculatorClient.cpp`` file with this -`content `_: +:fastdds-docs-tree:`content `: Examining the code """""""""""""""""" diff --git a/docs/fastddsgen/rpc_calculator_feed_app/intro.rst b/docs/fastddsgen/rpc_calculator_feed_app/intro.rst index 23589886ab..8e3bc62d9f 100644 --- a/docs/fastddsgen/rpc_calculator_feed_app/intro.rst +++ b/docs/fastddsgen/rpc_calculator_feed_app/intro.rst @@ -18,7 +18,7 @@ This section extends the previously discussed example of a calculator service * **filter**: Returns a feed of results with the received values that match an input filter. The entire example source code is available in this -`link `_ +:fastdds-docs-tree:`link ` .. include:: includes/background.rst .. include:: includes/workspace.rst diff --git a/docs/fastddsgen/usage/usage.rst b/docs/fastddsgen/usage/usage.rst index 5f121c2173..fd43f9f01b 100644 --- a/docs/fastddsgen/usage/usage.rst +++ b/docs/fastddsgen/usage/usage.rst @@ -75,7 +75,7 @@ Where the options are: - Specifies a custom template used for generating source code. This option expects the location of the template and the location of the file where source code output will be stored. - A custom template example can be found in this `link `_ + A custom template example can be found in this :fastddsgen-raw:`link ` * - -flat-output-dir - Ignores input files relative paths and place all generated files in the specified output directory. * - -help diff --git a/docs/installation/configuration/cmake_options.rst b/docs/installation/configuration/cmake_options.rst index 10ceee90dc..898122360b 100644 --- a/docs/installation/configuration/cmake_options.rst +++ b/docs/installation/configuration/cmake_options.rst @@ -88,8 +88,8 @@ dependency on other options. * - :class:`COMPILE_EXAMPLES` - Builds the *Fast DDS* examples. It is set to ``ON`` if :class:`EPROSIMA_BUILD` is ``ON`` and :class:`EPROSIMA_INSTALLER` is ``OFF``. These examples can be found in the - `eProsima Fast DDS `_ - `GitHub repository `_. + :fastdds-tree:`eProsima Fast DDS ` + :fastdds-tree:`GitHub repository `. - ``ON`` ``OFF`` - ``OFF`` * - :class:`INSTALL_EXAMPLES` diff --git a/docs/installation/sources/sources_linux.rst b/docs/installation/sources/sources_linux.rst index dbcc9e97cb..1faec3e51e 100644 --- a/docs/installation/sources/sources_linux.rst +++ b/docs/installation/sources/sources_linux.rst @@ -214,11 +214,11 @@ This section explains how to use it to compile *eProsima Fast DDS* and its depen #. Create a :code:`Fast-DDS` directory and download the repos file that will be used to install *eProsima Fast DDS* and its dependencies: - .. code-block:: bash + .. substitution-code-block:: bash mkdir ~/Fast-DDS cd ~/Fast-DDS - wget https://raw.githubusercontent.com/eProsima/Fast-DDS/master/fastdds.repos + wget https://raw.githubusercontent.com/eProsima/Fast-DDS/|FastDDSBranch|/fastdds.repos mkdir src vcs import src < fastdds.repos @@ -432,11 +432,11 @@ This section explains how to use it to compile *Fast DDS Python bindings* and it #. Create a :code:`Fast-DDS-python` directory and download the repos file that will be used to install *Fast DDS Python bindings* and its dependencies: - .. code-block:: bash + .. substitution-code-block:: bash mkdir ~/Fast-DDS-python cd ~/Fast-DDS-python - wget https://raw.githubusercontent.com/eProsima/Fast-DDS-python/main/fastdds_python.repos + wget https://raw.githubusercontent.com/eProsima/Fast-DDS-python/|FastDDSPythonBranch|/fastdds_python.repos mkdir src vcs import src < fastdds_python.repos diff --git a/docs/installation/sources/sources_mac.rst b/docs/installation/sources/sources_mac.rst index b60b5685e1..764d577fbd 100644 --- a/docs/installation/sources/sources_mac.rst +++ b/docs/installation/sources/sources_mac.rst @@ -165,11 +165,11 @@ This section explains how to use it to compile *eProsima Fast DDS* and its depen #. Create a :code:`Fast-DDS` directory and download the repos file that will be used to install *eProsima Fast DDS* and its dependencies: - .. code-block:: bash + .. substitution-code-block:: bash mkdir ~/Fast-DDS cd ~/Fast-DDS - wget https://raw.githubusercontent.com/eProsima/Fast-DDS/master/fastdds.repos + wget https://raw.githubusercontent.com/eProsima/Fast-DDS/|FastDDSBranch|/fastdds.repos mkdir src vcs import src < fastdds.repos diff --git a/docs/installation/sources/sources_windows.rst b/docs/installation/sources/sources_windows.rst index 973b4773c0..56e2c51888 100644 --- a/docs/installation/sources/sources_windows.rst +++ b/docs/installation/sources/sources_windows.rst @@ -267,11 +267,11 @@ This section explains how to use it to compile *eProsima Fast DDS* and its depen #. Create a :code:`Fast-DDS` directory and download the repos file that will be used to install *eProsima Fast DDS* and its dependencies: - .. code-block:: winbatch + .. substitution-code-block:: winbatch mkdir ~\Fast-DDS cd ~\Fast-DDS - wget https://raw.githubusercontent.com/eProsima/Fast-DDS/master/fastdds.repos -output fastdds.repos + wget https://raw.githubusercontent.com/eProsima/Fast-DDS/|FastDDSBranch|/fastdds.repos -output fastdds.repos mkdir src vcs import src --input fastdds.repos @@ -464,11 +464,11 @@ This section explains how to use it to compile *Fast DDS Python bindings* and it #. Create a :code:`Fast-DDS-python` directory and download the repos file that will be used to install *Fast DDS Python bindings* and its dependencies: - .. code-block:: winbatch + .. substitution-code-block:: winbatch mkdir ~\Fast-DDS-python cd ~\Fast-DDS-python - wget https://raw.githubusercontent.com/eProsima/Fast-DDS-python/main/fastdds_python.repos + wget https://raw.githubusercontent.com/eProsima/Fast-DDS-python/|FastDDSPythonBranch|/fastdds_python.repos mkdir src vcs import src --input fastdds_python.repos diff --git a/docs/notes/migration_guide.rst b/docs/notes/migration_guide.rst index 50e8bcf661..ab5944cf9d 100644 --- a/docs/notes/migration_guide.rst +++ b/docs/notes/migration_guide.rst @@ -401,4 +401,4 @@ Step 9: Examples refactor All examples in the Fast DDS project have been refactored to follow a consistent structure, having renamed files, restructured classes, and updated the overall format. If you have integrated any example into your own implementation, carefully review the updated examples to ensure compatibility with your project. As reference, -consider the example `Configuration `_. +consider the example :fastdds-tree:`Configuration `. diff --git a/docs/notes/notes.rst b/docs/notes/notes.rst index 3136967b45..7816d8ea9f 100644 --- a/docs/notes/notes.rst +++ b/docs/notes/notes.rst @@ -3,7 +3,7 @@ .. _release_notes: Information about the release lifecycle can be found -`here `_. +:fastdds-blob:`here `. .. include:: previous_versions/v3.5.0.rst diff --git a/docs/notes/previous_versions/v2.6.10.rst b/docs/notes/previous_versions/v2.6.10.rst index d1ff4c60e2..269ac49fdd 100644 --- a/docs/notes/previous_versions/v2.6.10.rst +++ b/docs/notes/previous_versions/v2.6.10.rst @@ -3,7 +3,7 @@ .. important:: According to our - `release support guidelines `_ + :fastdds-blob:`release support guidelines ` the v2.6 minor will only receive patches for critical issues and security fixes. This release includes the following **critical fixes**: diff --git a/docs/notes/previous_versions/v2.6.11.rst b/docs/notes/previous_versions/v2.6.11.rst index 83f066c40b..45907a024a 100644 --- a/docs/notes/previous_versions/v2.6.11.rst +++ b/docs/notes/previous_versions/v2.6.11.rst @@ -3,7 +3,7 @@ .. important:: According to our - `release support guidelines `_ + :fastdds-blob:`release support guidelines ` the v2.6 minor will only receive patches for critical issues and security fixes. This release includes the following **critical fixes**: diff --git a/docs/notes/previous_versions/v2.6.9.rst b/docs/notes/previous_versions/v2.6.9.rst index 9ab7895f8b..3d0fa3605d 100644 --- a/docs/notes/previous_versions/v2.6.9.rst +++ b/docs/notes/previous_versions/v2.6.9.rst @@ -3,7 +3,7 @@ .. important:: According to our - `release support guidelines `_ + :fastdds-blob:`release support guidelines ` Fast DDS v2.6.9 will be the last patch version receiving backported features and bugfixes. From now on, the v2.6 minor will only receive patches for critical issues and security fixes. diff --git a/docs/notes/previous_versions/v3.0.0.rst b/docs/notes/previous_versions/v3.0.0.rst index ca48e699cf..2fbe0f3f23 100644 --- a/docs/notes/previous_versions/v3.0.0.rst +++ b/docs/notes/previous_versions/v3.0.0.rst @@ -3,7 +3,7 @@ Fast DDS v3.0.0 is a mayor release that entails some **API breaks** and new features. This version is **not backwards compatible** with previous versions. -Refer to the `migration guide `__ for hints moving to Fast DDS v3.0.0. +Refer to the :fastdds-blob:`migration guide ` for hints moving to Fast DDS v3.0.0. This release includes the following **API breaks**: @@ -27,7 +27,7 @@ This release includes the following **API breaks**: #. Move ``DataReader::TypeConsistencyEnforcement`` and ``DataReader::DataRepresentation`` from ``TypeConsistency`` to ``DataReaderQos``. #. Migrate ``BuiltinEndpoints`` defines to variables. #. Remove ``string_convert`` header and source. -#. `Examples `__ refactor. +#. :fastdds-blob:`Examples ` refactor. #. Update Fast DDS docs QoS examples. #. Link SHM locator kind with Fast DDS major version. #. Discard local SHM locators that cannot be opened. @@ -56,7 +56,7 @@ This release includes the following **improvements**: #. Setting ``vendor_id`` on received ``CacheChange_t``. #. Builtin data related improvements. #. GitHub repository management. -#. `Migration guide `__. +#. :fastdds-blob:`Migration guide `. #. Update fastcdr thirdparty. #. Documentation updates due to major version change. diff --git a/docs/notes/versions.rst b/docs/notes/versions.rst index 2fa478ae0a..5a865987ff 100644 --- a/docs/notes/versions.rst +++ b/docs/notes/versions.rst @@ -366,7 +366,7 @@ The following table shows the minimum version required of the Fast DDS build sys .. important:: According to our - `release support guidelines `_ + :fastdds-blob:`release support guidelines ` Fast DDS v2.6.9 will be the last patch version receiving backported features and bugfixes. From now on, the v2.6 minor will only receive patches for critical issues and security fixes. @@ -476,7 +476,7 @@ The following table shows the corresponding versions of the Fast DDS library dep .. important:: According to our - `release support guidelines `_ + :fastdds-blob:`release support guidelines ` Fast DDS v2.6.9 will be the last patch version receiving backported features and bugfixes. From now on, the v2.6 minor will only receive patches for critical issues and security fixes. @@ -585,6 +585,6 @@ Fast DDS as the core middleware. .. important:: According to our - `release support guidelines `_ + :fastdds-blob:`release support guidelines ` Fast DDS v2.6.9 will be the last patch version receiving backported features and bugfixes. From now on, the v2.6 minor will only receive patches for critical issues and security fixes. From 05e9b7e8588a149c15997be43faa5a6c1243ea3f Mon Sep 17 00:00:00 2001 From: Emilio Cuesta Date: Wed, 25 Mar 2026 15:00:11 +0100 Subject: [PATCH 02/10] Minor branch fix Signed-off-by: Emilio Cuesta --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 7a2e6a2173..b5f1754788 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -575,7 +575,7 @@ def configure_doxyfile( # Branch used for all Fast-DDS / Fast-DDS-docs / Fast-DDS-Gen links. # Change this when branching for a release (e.g. "3.2.x", "3.2.0"). -fastdds_fallback_branch = "master" +fastdds_fallback_branch = "main" # Branch used for Fast-DDS-python links (default branch is "main"). fastdds_python_branch = "main" From 0e96aac4a48c48fa3e9497997543d6d52e5222d3 Mon Sep 17 00:00:00 2001 From: Emilio Cuesta Date: Thu, 26 Mar 2026 08:29:08 +0100 Subject: [PATCH 03/10] Separate python_branch and python fallback branch Signed-off-by: Emilio Cuesta --- docs/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index b5f1754788..ebf3623585 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -495,7 +495,7 @@ def configure_doxyfile( ), # Fast-DDS-python repo "fastdds-python-tree": ( - f"https://github.com/eProsima/Fast-DDS-python/tree/{fastdds_python_branch}/%s", "%s" + f"https://github.com/eProsima/Fast-DDS-python/tree/{fastdds_python_fallback_branch}/%s", "%s" ), # Fast-DDS-docs repo (code examples embedded in the docs repo) "fastdds-docs-tree": ( @@ -578,7 +578,7 @@ def configure_doxyfile( fastdds_fallback_branch = "main" # Branch used for Fast-DDS-python links (default branch is "main"). -fastdds_python_branch = "main" +fastdds_python_fallback_branch = "main" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -718,7 +718,7 @@ def configure_doxyfile( .. |FastDDSBranch| replace:: {fastdds_fallback_branch} -.. |FastDDSPythonBranch| replace:: {fastdds_python_branch} +.. |FastDDSPythonBranch| replace:: {fastdds_python_fallback_branch} """ From bc44e45de2f5bba488c58b748fd6d2656165d66e Mon Sep 17 00:00:00 2001 From: Emilio Cuesta Date: Thu, 26 Mar 2026 08:35:48 +0100 Subject: [PATCH 04/10] Update repos Signed-off-by: Emilio Cuesta --- docs/conf.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ebf3623585..c6935151f7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -488,22 +488,22 @@ def configure_doxyfile( extlinks = { # Fast-DDS repo (tree = directory, blob = file) "fastdds-tree": ( - f"https://github.com/eProsima/Fast-DDS/tree/{fastdds_fallback_branch}/%s", "%s" + f"https://github.com/eProsima/Fast-DDS-Pro/tree/{fastdds_fallback_branch}/%s", "%s" ), "fastdds-blob": ( - f"https://github.com/eProsima/Fast-DDS/blob/{fastdds_fallback_branch}/%s", "%s" + f"https://github.com/eProsima/Fast-DDS-Pro/blob/{fastdds_fallback_branch}/%s", "%s" ), # Fast-DDS-python repo "fastdds-python-tree": ( - f"https://github.com/eProsima/Fast-DDS-python/tree/{fastdds_python_fallback_branch}/%s", "%s" + f"https://github.com/eProsima/Fast-DDS-Pro-Python/tree/{fastdds_python_fallback_branch}/%s", "%s" ), # Fast-DDS-docs repo (code examples embedded in the docs repo) "fastdds-docs-tree": ( - f"https://github.com/eProsima/Fast-DDS-docs/tree/{fastdds_fallback_branch}/%s", "%s" + f"https://github.com/eProsima/Fast-DDS-Pro-docs/tree/{fastdds_docs_fallback_branch}/%s", "%s" ), # Fast-DDS-Gen raw files "fastddsgen-raw": ( - f"https://raw.githubusercontent.com/eProsima/Fast-DDS-Gen/{fastdds_fallback_branch}/%s", + f"https://raw.githubusercontent.com/eProsima/Fast-DDS-Gen/{fastdds_gen_fallback_branch}/%s", "%s", ), } @@ -576,9 +576,11 @@ def configure_doxyfile( # Branch used for all Fast-DDS / Fast-DDS-docs / Fast-DDS-Gen links. # Change this when branching for a release (e.g. "3.2.x", "3.2.0"). fastdds_fallback_branch = "main" - +fastdds_docs_fallback_branch = fastdds_fallback_branch # Branch used for Fast-DDS-python links (default branch is "main"). fastdds_python_fallback_branch = "main" +# Branch used for Fast-DDS-Gen links (default branch is "master"). +fastdds_gen_fallback_branch = "master" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. From 2e2b16fde3b94023e24b8ef3fe19d59d2f04382f Mon Sep 17 00:00:00 2001 From: Emilio Cuesta Date: Thu, 26 Mar 2026 12:13:20 +0100 Subject: [PATCH 05/10] Add same fallback logic as in ReadTheDocs checkouts and logs Signed-off-by: Emilio Cuesta --- docs/conf.py | 83 ++++++++++++++++++++++++++++------------------------ 1 file changed, 44 insertions(+), 39 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index c6935151f7..5603523bdf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -276,6 +276,21 @@ def get_git_branch(): return None +def resolve_fallback_branch(env_var, docs_branch, default="main"): + """ + Resolve the branch to use for GitHub links. + + Priority: + 1. Environment variable ``env_var`` (e.g. FASTDDS_BRANCH) + 2. Current documentation branch (``docs_branch``) + 3. Hard-coded ``default`` + + This mirrors the checkout logic used in the ReadTheDocs clone block so + that extlinks and the actual checkout always point at the same branch. + """ + return os.environ.get(env_var) or docs_branch or default + + def configure_doxyfile( doxyfile_in, doxyfile_out, @@ -323,6 +338,10 @@ def configure_doxyfile( # Header files input_dir = os.path.abspath("{}/fastdds/include/fastdds".format(project_binary_dir)) +# Current branch of the documentation repository — resolved once, used everywhere. +docs_branch = get_git_branch() +print('Current documentation branch is "{}"'.format(docs_branch)) + # Check if we're running on Read the Docs' servers read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True" if read_the_docs_build: @@ -355,24 +374,15 @@ def configure_doxyfile( fastdds_repo_name, ) - # Documentation repository branch - docs_branch = get_git_branch() - print('Current documentation branch is "{}"'.format(docs_branch)) - - # User specified Fast DDS branch - fastdds_branch = os.environ.get("FASTDDS_BRANCH", None) - - # First try to checkout to ${FASTDDS_BRANCH} - # Else try with current documentation branch - # Else checkout to master - if fastdds_branch and fastdds.refs.__contains__("origin/{}".format(fastdds_branch)): + # Resolve desired branch (env var → current docs branch → main) then verify + # it actually exists in the cloned remote, falling back to main if not. + fastdds_branch = resolve_fallback_branch("FASTDDS_BRANCH", docs_branch, "main") + if fastdds.refs.__contains__("origin/{}".format(fastdds_branch)): fastdds_branch = "origin/{}".format(fastdds_branch) - elif docs_branch and fastdds.refs.__contains__("origin/{}".format(docs_branch)): - fastdds_branch = "origin/{}".format(docs_branch) else: print( - 'Fast DDS does not have either "{}" or "{}" branches'.format( - fastdds_branch, docs_branch + 'Fast DDS does not have branch "{}"; falling back to main'.format( + fastdds_branch ) ) fastdds_branch = "origin/master" @@ -388,24 +398,15 @@ def configure_doxyfile( fastdds_python_repo_name, ) - # User specified Fast DDS branch - fastdds_python_branch = os.environ.get("FASTDDS_PYTHON_BRANCH", None) - - # First try to checkout to ${FASTDDS_PYTHON_BRANCH} - # Else try with current documentation branch - # Else checkout to master - if fastdds_python_branch and fastdds_python.refs.__contains__( - "origin/{}".format(fastdds_python_branch) - ): + # Resolve desired branch (env var → current docs branch → main) then verify + # it actually exists in the cloned remote, falling back to main if not. + fastdds_python_branch = resolve_fallback_branch("FASTDDS_PYTHON_BRANCH", docs_branch, "main") + if fastdds_python.refs.__contains__("origin/{}".format(fastdds_python_branch)): fastdds_python_branch = "origin/{}".format(fastdds_python_branch) - elif docs_branch and fastdds_python.refs.__contains__( - "origin/{}".format(docs_branch) - ): - fastdds_python_branch = "origin/{}".format(docs_branch) else: print( - 'Fast DDS Python does not have either "{}" or "{}" branches'.format( - fastdds_python_branch, docs_branch + 'Fast DDS Python does not have branch "{}"; falling back to main'.format( + fastdds_python_branch ) ) fastdds_python_branch = "origin/master" @@ -485,6 +486,19 @@ def configure_doxyfile( "sphinx_toolbox.collapse", ] +# Resolve GitHub link branches using the same priority as the ReadTheDocs +# checkout logic: env var → branch with same name as current docs branch → master/main +fastdds_fallback_branch = resolve_fallback_branch("FASTDDS_BRANCH", docs_branch, "main") +fastdds_docs_fallback_branch = docs_branch +fastdds_python_fallback_branch = resolve_fallback_branch("FASTDDS_PYTHON_BRANCH", docs_branch, "main") +fastdds_gen_fallback_branch = resolve_fallback_branch("FASTDDS_GEN_BRANCH", docs_branch, "master") + +print("Fallback branches for GitHub links:") +print(' Fast-DDS: "{}"'.format(fastdds_fallback_branch)) +print(' Fast-DDS-docs: "{}"'.format(fastdds_docs_fallback_branch)) +print(' Fast-DDS-Python: "{}"'.format(fastdds_python_fallback_branch)) +print(' Fast-DDS-Gen: "{}"'.format(fastdds_gen_fallback_branch)) + extlinks = { # Fast-DDS repo (tree = directory, blob = file) "fastdds-tree": ( @@ -573,15 +587,6 @@ def configure_doxyfile( # The full version, including alpha/beta/rc tags. release = "3.6.0" -# Branch used for all Fast-DDS / Fast-DDS-docs / Fast-DDS-Gen links. -# Change this when branching for a release (e.g. "3.2.x", "3.2.0"). -fastdds_fallback_branch = "main" -fastdds_docs_fallback_branch = fastdds_fallback_branch -# Branch used for Fast-DDS-python links (default branch is "main"). -fastdds_python_fallback_branch = "main" -# Branch used for Fast-DDS-Gen links (default branch is "master"). -fastdds_gen_fallback_branch = "master" - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # From 93fcff7d506b78e52b6a3d6d44db01c32c8022d6 Mon Sep 17 00:00:00 2001 From: Emilio Cuesta Date: Fri, 27 Mar 2026 08:14:41 +0100 Subject: [PATCH 06/10] Changes substitution-block per code-block Signed-off-by: Emilio Cuesta --- docs/installation/sources/sources_linux.rst | 6 ++++-- docs/installation/sources/sources_mac.rst | 3 ++- docs/installation/sources/sources_windows.rst | 6 ++++-- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/installation/sources/sources_linux.rst b/docs/installation/sources/sources_linux.rst index 1faec3e51e..ba91225a5f 100644 --- a/docs/installation/sources/sources_linux.rst +++ b/docs/installation/sources/sources_linux.rst @@ -214,7 +214,8 @@ This section explains how to use it to compile *eProsima Fast DDS* and its depen #. Create a :code:`Fast-DDS` directory and download the repos file that will be used to install *eProsima Fast DDS* and its dependencies: - .. substitution-code-block:: bash + .. code-block:: bash + :substitutions: mkdir ~/Fast-DDS cd ~/Fast-DDS @@ -432,7 +433,8 @@ This section explains how to use it to compile *Fast DDS Python bindings* and it #. Create a :code:`Fast-DDS-python` directory and download the repos file that will be used to install *Fast DDS Python bindings* and its dependencies: - .. substitution-code-block:: bash + .. code-block:: bash + :substitutions: mkdir ~/Fast-DDS-python cd ~/Fast-DDS-python diff --git a/docs/installation/sources/sources_mac.rst b/docs/installation/sources/sources_mac.rst index 764d577fbd..6f6015c8d1 100644 --- a/docs/installation/sources/sources_mac.rst +++ b/docs/installation/sources/sources_mac.rst @@ -165,7 +165,8 @@ This section explains how to use it to compile *eProsima Fast DDS* and its depen #. Create a :code:`Fast-DDS` directory and download the repos file that will be used to install *eProsima Fast DDS* and its dependencies: - .. substitution-code-block:: bash + .. code-block:: bash + :substitutions: mkdir ~/Fast-DDS cd ~/Fast-DDS diff --git a/docs/installation/sources/sources_windows.rst b/docs/installation/sources/sources_windows.rst index 56e2c51888..5996d9791d 100644 --- a/docs/installation/sources/sources_windows.rst +++ b/docs/installation/sources/sources_windows.rst @@ -267,7 +267,8 @@ This section explains how to use it to compile *eProsima Fast DDS* and its depen #. Create a :code:`Fast-DDS` directory and download the repos file that will be used to install *eProsima Fast DDS* and its dependencies: - .. substitution-code-block:: winbatch + .. code-block:: winbatch + :substitutions: mkdir ~\Fast-DDS cd ~\Fast-DDS @@ -464,7 +465,8 @@ This section explains how to use it to compile *Fast DDS Python bindings* and it #. Create a :code:`Fast-DDS-python` directory and download the repos file that will be used to install *Fast DDS Python bindings* and its dependencies: - .. substitution-code-block:: winbatch + .. code-block:: winbatch + :substitutions: mkdir ~\Fast-DDS-python cd ~\Fast-DDS-python From 8cbee1cff10f888b21318cc4cbd4dfd46ed83ac6 Mon Sep 17 00:00:00 2001 From: Emilio Cuesta Date: Mon, 30 Mar 2026 09:32:49 +0200 Subject: [PATCH 07/10] Fix refs Signed-off-by: Emilio Cuesta --- docs/conf.py | 8 ++++---- docs/fastdds/discovery/discovery_server.rst | 5 +++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5603523bdf..74e6a8cd34 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -502,18 +502,18 @@ def configure_doxyfile( extlinks = { # Fast-DDS repo (tree = directory, blob = file) "fastdds-tree": ( - f"https://github.com/eProsima/Fast-DDS-Pro/tree/{fastdds_fallback_branch}/%s", "%s" + f"https://github.com/eProsima/Fast-DDS/tree/{fastdds_fallback_branch}/%s", "%s" ), "fastdds-blob": ( - f"https://github.com/eProsima/Fast-DDS-Pro/blob/{fastdds_fallback_branch}/%s", "%s" + f"https://github.com/eProsima/Fast-DDS/blob/{fastdds_fallback_branch}/%s", "%s" ), # Fast-DDS-python repo "fastdds-python-tree": ( - f"https://github.com/eProsima/Fast-DDS-Pro-Python/tree/{fastdds_python_fallback_branch}/%s", "%s" + f"https://github.com/eProsima/Fast-DDS-Python/tree/{fastdds_python_fallback_branch}/%s", "%s" ), # Fast-DDS-docs repo (code examples embedded in the docs repo) "fastdds-docs-tree": ( - f"https://github.com/eProsima/Fast-DDS-Pro-docs/tree/{fastdds_docs_fallback_branch}/%s", "%s" + f"https://github.com/eProsima/Fast-DDS-docs/tree/{fastdds_docs_fallback_branch}/%s", "%s" ), # Fast-DDS-Gen raw files "fastddsgen-raw": ( diff --git a/docs/fastdds/discovery/discovery_server.rst b/docs/fastdds/discovery/discovery_server.rst index d2921899f4..f1f4e0abb8 100644 --- a/docs/fastdds/discovery/discovery_server.rst +++ b/docs/fastdds/discovery/discovery_server.rst @@ -315,8 +315,9 @@ Full example ^^^^^^^^^^^^ The following constitutes a full example on how to configure *server* and *client* both programmatically and using XML. -You may also have a look at the *eProsima Fast DDS* Github repository, which contains :fastdds-tree:`an example ` -similar to the one discussed in this section, as well as multiple other examples for different use cases. +You may also have a look at the *eProsima Fast DDS* Github repository, which contains +:fastdds-tree:`an example ` similar to the one discussed in this section, as well as +multiple other examples for different use cases. Server side setup """"""""""""""""" From a7536e4553456caf17474e02e6c46a2aa95dbd43 Mon Sep 17 00:00:00 2001 From: Emilio Cuesta Date: Mon, 30 Mar 2026 10:20:25 +0200 Subject: [PATCH 08/10] Tests with read the docs env variables Signed-off-by: Emilio Cuesta --- docs/conf.py | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 74e6a8cd34..b3b2971d86 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -248,7 +248,25 @@ def static_relative(path): def get_git_branch(): - """Get the git branch this repository is currently on.""" + """Get the git branch this repository is currently on. + + On Read the Docs the repo is checked out in detached-HEAD mode, so + ``git name-rev`` returns synthetic names like ``remotes/origin/external-1234`` + instead of the real branch. RTD always exports a human-readable version + name in ``READTHEDOCS_VERSION``: the branch name for branch builds, the tag + name for tag builds, and the PR number for PR preview builds. All of these + are more useful than the synthetic git name; PR numbers simply won't match + any remote branch and resolve_fallback_branch will fall back to the default. + """ + # On RTD, READTHEDOCS_VERSION is the human-readable version name: + # a branch name for branch builds, a tag name for tag builds, and + # the PR number for external (PR preview) builds. All of these are + # better than the synthetic "external-1234" that git name-rev returns. + # For PR builds the number won't match any Fast-DDS branch, so + # resolve_fallback_branch will simply fall through to its default. + if os.environ.get("READTHEDOCS") == "True": + return os.environ.get("READTHEDOCS_VERSION") + path_to_here = os.path.abspath(os.path.dirname(__file__)) # Invoke git to get the current branch which we use to get the theme @@ -341,6 +359,11 @@ def configure_doxyfile( # Current branch of the documentation repository — resolved once, used everywhere. docs_branch = get_git_branch() print('Current documentation branch is "{}"'.format(docs_branch)) +print('READTHEDOCS_VERSION="{}" READTHEDOCS_VERSION_TYPE="{}" READTHEDOCS_GIT_IDENTIFIER="{}"'.format( + os.environ.get("READTHEDOCS_VERSION", ""), + os.environ.get("READTHEDOCS_VERSION_TYPE", ""), + os.environ.get("READTHEDOCS_GIT_IDENTIFIER", ""), +)) # Check if we're running on Read the Docs' servers read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True" From f22f1ba68a509b5919a9eebc1a58a93c21241dd1 Mon Sep 17 00:00:00 2001 From: Emilio Cuesta Date: Mon, 30 Mar 2026 10:54:46 +0200 Subject: [PATCH 09/10] Resolving problem when building from RTD Signed-off-by: Emilio Cuesta --- docs/conf.py | 70 +++++++++++++++++++++++++++------------------------- 1 file changed, 37 insertions(+), 33 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index b3b2971d86..154a21c596 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -252,20 +252,20 @@ def get_git_branch(): On Read the Docs the repo is checked out in detached-HEAD mode, so ``git name-rev`` returns synthetic names like ``remotes/origin/external-1234`` - instead of the real branch. RTD always exports a human-readable version - name in ``READTHEDOCS_VERSION``: the branch name for branch builds, the tag - name for tag builds, and the PR number for PR preview builds. All of these - are more useful than the synthetic git name; PR numbers simply won't match - any remote branch and resolve_fallback_branch will fall back to the default. + instead of the real branch. A workaround is provided using + ``READTHEDOCS_VERSION_TYPE`` and ``READTHEDOCS_VERSION`` according to the build type: + - ``"branch"`` builds: READTHEDOCS_VERSION is the branch name (e.g. ``"3.6.x"``) → use it. + - ``"tag"`` builds: READTHEDOCS_VERSION is the tag name (e.g. ``"v3.6.0"``) → use it. + - ``"external"`` (PR preview) builds: READTHEDOCS_VERSION is the PR number (e.g. ``"1241"``) + which is not a valid git ref. In this case we return None so resolve_fallback_branch falls + back to its default instead of generating broken GitHub URLs. + - Local builds: READTHEDOCS_VERSION_TYPE is unset → fall back to git name-rev. """ - # On RTD, READTHEDOCS_VERSION is the human-readable version name: - # a branch name for branch builds, a tag name for tag builds, and - # the PR number for external (PR preview) builds. All of these are - # better than the synthetic "external-1234" that git name-rev returns. - # For PR builds the number won't match any Fast-DDS branch, so - # resolve_fallback_branch will simply fall through to its default. - if os.environ.get("READTHEDOCS") == "True": + rtd_type = os.environ.get("READTHEDOCS_VERSION_TYPE") + if rtd_type in ("branch", "tag"): return os.environ.get("READTHEDOCS_VERSION") + if rtd_type == "external": + return None path_to_here = os.path.abspath(os.path.dirname(__file__)) @@ -288,6 +288,7 @@ def get_git_branch(): return p.communicate()[0].decode().rstrip() except Exception: + # Local build without git or some error occurred print("Could not get the branch") # Couldn't figure out the branch probably due to an error @@ -358,12 +359,24 @@ def configure_doxyfile( # Current branch of the documentation repository — resolved once, used everywhere. docs_branch = get_git_branch() -print('Current documentation branch is "{}"'.format(docs_branch)) -print('READTHEDOCS_VERSION="{}" READTHEDOCS_VERSION_TYPE="{}" READTHEDOCS_GIT_IDENTIFIER="{}"'.format( - os.environ.get("READTHEDOCS_VERSION", ""), - os.environ.get("READTHEDOCS_VERSION_TYPE", ""), - os.environ.get("READTHEDOCS_GIT_IDENTIFIER", ""), -)) +if docs_branch: + print('Current documentation branch is "{}"'.format(docs_branch)) +else: + print("Current documentation branch could not be determined; " \ + "GitHub links will point to default branches instead of the corresponding branch.") + +# Resolve GitHub link branches: env var → current docs branch → default. +# Computed here so they are available both in the ReadTheDocs clone block and in extlinks. +fastdds_fallback_branch = resolve_fallback_branch("FASTDDS_BRANCH", docs_branch, "master") +fastdds_docs_fallback_branch = docs_branch +fastdds_python_fallback_branch = resolve_fallback_branch("FASTDDS_PYTHON_BRANCH", docs_branch, "master") +fastdds_gen_fallback_branch = resolve_fallback_branch("FASTDDS_GEN_BRANCH", docs_branch, "master") + +print("Fallback branches for GitHub links:") +print(' Fast-DDS: "{}"'.format(fastdds_fallback_branch)) +print(' Fast-DDS-docs: "{}"'.format(fastdds_docs_fallback_branch)) +print(' Fast-DDS-Python: "{}"'.format(fastdds_python_fallback_branch)) +print(' Fast-DDS-Gen: "{}"'.format(fastdds_gen_fallback_branch)) # Check if we're running on Read the Docs' servers read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True" @@ -397,14 +410,13 @@ def configure_doxyfile( fastdds_repo_name, ) - # Resolve desired branch (env var → current docs branch → main) then verify - # it actually exists in the cloned remote, falling back to main if not. - fastdds_branch = resolve_fallback_branch("FASTDDS_BRANCH", docs_branch, "main") + # Verify the desired branch actually exists in the cloned remote, falling back to master if not. + fastdds_branch = fastdds_fallback_branch if fastdds.refs.__contains__("origin/{}".format(fastdds_branch)): fastdds_branch = "origin/{}".format(fastdds_branch) else: print( - 'Fast DDS does not have branch "{}"; falling back to main'.format( + 'Fast DDS does not have branch "{}"; falling back to master'.format( fastdds_branch ) ) @@ -421,14 +433,13 @@ def configure_doxyfile( fastdds_python_repo_name, ) - # Resolve desired branch (env var → current docs branch → main) then verify - # it actually exists in the cloned remote, falling back to main if not. - fastdds_python_branch = resolve_fallback_branch("FASTDDS_PYTHON_BRANCH", docs_branch, "main") + # Verify the desired branch actually exists in the cloned remote, falling back to master if not. + fastdds_python_branch = fastdds_python_fallback_branch if fastdds_python.refs.__contains__("origin/{}".format(fastdds_python_branch)): fastdds_python_branch = "origin/{}".format(fastdds_python_branch) else: print( - 'Fast DDS Python does not have branch "{}"; falling back to main'.format( + 'Fast DDS Python does not have branch "{}"; falling back to master'.format( fastdds_python_branch ) ) @@ -509,13 +520,6 @@ def configure_doxyfile( "sphinx_toolbox.collapse", ] -# Resolve GitHub link branches using the same priority as the ReadTheDocs -# checkout logic: env var → branch with same name as current docs branch → master/main -fastdds_fallback_branch = resolve_fallback_branch("FASTDDS_BRANCH", docs_branch, "main") -fastdds_docs_fallback_branch = docs_branch -fastdds_python_fallback_branch = resolve_fallback_branch("FASTDDS_PYTHON_BRANCH", docs_branch, "main") -fastdds_gen_fallback_branch = resolve_fallback_branch("FASTDDS_GEN_BRANCH", docs_branch, "master") - print("Fallback branches for GitHub links:") print(' Fast-DDS: "{}"'.format(fastdds_fallback_branch)) print(' Fast-DDS-docs: "{}"'.format(fastdds_docs_fallback_branch)) From fb9a94ce53977ad51eadd102bfc01c066e18b95c Mon Sep 17 00:00:00 2001 From: Emilio Cuesta Date: Wed, 1 Apr 2026 17:18:59 +0200 Subject: [PATCH 10/10] Apply review Signed-off-by: Emilio Cuesta --- docs/conf.py | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 154a21c596..3d45ece508 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -295,7 +295,7 @@ def get_git_branch(): return None -def resolve_fallback_branch(env_var, docs_branch, default="main"): +def resolve_fallback_branch(env_var, docs_branch, default="master"): """ Resolve the branch to use for GitHub links. @@ -368,7 +368,7 @@ def configure_doxyfile( # Resolve GitHub link branches: env var → current docs branch → default. # Computed here so they are available both in the ReadTheDocs clone block and in extlinks. fastdds_fallback_branch = resolve_fallback_branch("FASTDDS_BRANCH", docs_branch, "master") -fastdds_docs_fallback_branch = docs_branch +fastdds_docs_fallback_branch = resolve_fallback_branch("FASTDDS_DOCS_BRANCH", docs_branch, "master") fastdds_python_fallback_branch = resolve_fallback_branch("FASTDDS_PYTHON_BRANCH", docs_branch, "master") fastdds_gen_fallback_branch = resolve_fallback_branch("FASTDDS_GEN_BRANCH", docs_branch, "master") @@ -520,12 +520,6 @@ def configure_doxyfile( "sphinx_toolbox.collapse", ] -print("Fallback branches for GitHub links:") -print(' Fast-DDS: "{}"'.format(fastdds_fallback_branch)) -print(' Fast-DDS-docs: "{}"'.format(fastdds_docs_fallback_branch)) -print(' Fast-DDS-Python: "{}"'.format(fastdds_python_fallback_branch)) -print(' Fast-DDS-Gen: "{}"'.format(fastdds_gen_fallback_branch)) - extlinks = { # Fast-DDS repo (tree = directory, blob = file) "fastdds-tree": (