[24299] Add fallback branch for master links

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.  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.
+    """
+    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__))
 
     # Invoke git to get the current branch which we use to get the theme
@@ -270,12 +288,28 @@ 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
     return None
 
 
+def resolve_fallback_branch(env_var, docs_branch, default="master"):
+    """
+    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 +357,27 @@ 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()
+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 = 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")
+
+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"
 if read_the_docs_build:
@@ -355,24 +410,14 @@ 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)):
+    # 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)
-    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 master'.format(
+                fastdds_branch
             )
         )
         fastdds_branch = "origin/master"
@@ -388,24 +433,14 @@ 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)
-    ):
+    # 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)
-    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 master'.format(
+                fastdds_python_branch
             )
         )
         fastdds_python_branch = "origin/master"
@@ -480,10 +515,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_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_docs_fallback_branch}/%s", "%s"
+    ),
+    # Fast-DDS-Gen raw files
+    "fastddsgen-raw": (
+        f"https://raw.githubusercontent.com/eProsima/Fast-DDS-Gen/{fastdds_gen_fallback_branch}/%s",
+        "%s",
+    ),
+}
+
 sphinx_tabs_disable_css_loading = False
 sphinx_tabs_disable_tab_closing = True
 
@@ -684,6 +743,10 @@ def configure_doxyfile(
     <span class="sd-badge sd-outline-primary sd-text-primary" title="Exclusive to Fast DDS Pro">Pro</span>
 
 .. |ProjectVersion| replace:: {version}
+
+.. |FastDDSBranch| replace:: {fastdds_fallback_branch}
+
+.. |FastDDSPythonBranch| replace:: {fastdds_python_fallback_branch}
 """
 
 

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 `an example <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/discovery_server>`_
-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 <examples/cpp/discovery_server>` similar to the one discussed in this section, as well as
+multiple other examples for different use cases.
 
 Server side setup
 """""""""""""""""

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 <https://github.com/eProsima/Fast-DDS/blob/master/examples/cpp/dds/StaticHelloWorldExample>`_
+:fastdds-blob:`Static Discovery example <examples/cpp/dds/StaticHelloWorldExample>`
 that implements this EDP discovery protocol.
 
 The following table describes all the possible elements of a STATIC EDP XML configuration file.

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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp>`_.
+:fastdds-tree:`here <examples/cpp>`.

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 <https://github.com/eProsima/Fast-DDS-python/tree/master/fastdds_python_examples>`_.
+:fastdds-python-tree:`here <fastdds_python_examples>`.

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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/rtps>`_.
+:fastdds-tree:`examples/cpp/rtps <examples/cpp/rtps>`.
 
 Managing the Participant
 ^^^^^^^^^^^^^^^^^^^^^^^^

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 <https://github.com/eProsima/Fast-DDS/blob/master/resources/xsd/governance.xsd>`_ and
+The :fastdds-blob:`Governance XSD file <resources/xsd/governance.xsd>` and
 the
-`Governance XML example <https://github.com/eProsima/Fast-DDS/blob/master/examples/cpp/dds/SecureHelloWorldExample/certs/governance.xml>`_
+:fastdds-blob:`Governance XML example <examples/cpp/dds/SecureHelloWorldExample/certs/governance.xml>`
 can also be downloaded from the `eProsima Fast DDS Github repository <https://github.com/eProsima/Fast-DDS>`_.
 
 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 <https://github.com/eProsima/Fast-DDS/blob/master/resources/xsd/governance.xsd>`_ and
+The :fastdds-blob:`Permissions XSD file <resources/xsd/governance.xsd>` and
 the
-`Permissions XML example <https://github.com/eProsima/Fast-DDS/blob/master/examples/cpp/dds/SecureHelloWorldExample/certs/governance.xml>`_
+:fastdds-blob:`Permissions XML example <examples/cpp/dds/SecureHelloWorldExample/certs/governance.xml>`
 can also be downloaded from the `eProsima Fast DDS Github repository <https://github.com/eProsima/Fast-DDS>`_.
 
 Grant Section

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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/delivery_mechanisms>`_.
+:fastdds-tree:`delivery_mechanisms folder <examples/cpp/delivery_mechanisms>`.
 It shows a publisher and a subscriber that communicate through the desired delivery mechanism (which can be set to
 shared memory only).

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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/delivery_mechanisms>`_.
+:fastdds-tree:`delivery_mechanisms folder <examples/cpp/delivery_mechanisms>`.
 It shows a publisher and a subscriber that communicate through the desired delivery mechanism (which can be set to TCP
 only).

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 <examples/cpp/request_reply>`.
 
 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

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 <https://github.com/eProsima/Fast-DDS/blob/master/include/fastdds/statistics/types.idl>`_
+* Using the :fastdds-blob:`statistics IDL <include/fastdds/statistics/types.idl>`
   provided in the public API, generate the |TopicDataTypes-api| with :ref:`Fast DDS-Gen <fastddsgen_usage>`.
 
 * Create the |DomainParticipant-api| and register the |TopicDataTypes-api| and the corresponding statistics

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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/static_edp_discovery>`_
+:fastdds-tree:`examples/cpp/static_edp_discovery <examples/cpp/static_edp_discovery>`
 folder.
 
 The following subsections present an example configuration where a Publisher in

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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/delivery_mechanisms>`_.
+:fastdds-tree:`delivery_mechanisms folder <examples/cpp/delivery_mechanisms>`.
 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.

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 <https://github.com/eProsima/Fast-DDS/blob/master/resources/xsd/fastdds_profiles.xsd>`_
+    :fastdds-blob:`Fast DDS XSD scheme <resources/xsd/fastdds_profiles.xsd>`
     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 <https://github.com/eProsima/Fast-DDS/blob/master/resources/xsd/fastdds_profiles.xsd>`_
+    The :fastdds-blob:`Fast DDS XSD schema <resources/xsd/fastdds_profiles.xsd>`
     does not support the environment variables expansion feature, so validation of an XML file with environment
     variables expansion expressions will fail.

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 <https://github.com/eProsima/Fast-DDS/tree/master/examples>`_
+:fastdds-tree:`eProsima Fast DDS examples on github <examples>`
 for ideas on how to improve this basic application through different configuration
 options, and also for examples of advanced *Fast DDS* features.

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 <https://github.com/eProsima/Fast-DDS-docs/tree/master/code/Examples/
-C++/RpcClientServerBasic/src/CalculatorClient.cpp>`_:
+:fastdds-docs-tree:`content <code/Examples/C++/RpcClientServerBasic/src/CalculatorClient.cpp>`:
 
 Examining the code
 """"""""""""""""""

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 <https://github.com/eProsima/Fast-DDS-docs/tree/master/code/Examples/C++/RpcClientServerBasic>`_
+:fastdds-docs-tree:`link <code/Examples/C++/RpcClientServerBasic>`
 
 .. include:: includes/background.rst
 .. include:: includes/prerequisites.rst

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 <https://github.com/eProsima/Fast-DDS-docs/tree/master/code/Examples/
-C++/RpcClientServerFeed/src/CalculatorClient.cpp>`_:
+:fastdds-docs-tree:`content <code/Examples/C++/RpcClientServerFeed/src/CalculatorClient.cpp>`:
 
 Examining the code
 """"""""""""""""""

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 <https://github.com/eProsima/Fast-DDS-docs/tree/master/code/Examples/C++/RpcClientServerFeed>`_
+:fastdds-docs-tree:`link <code/Examples/C++/RpcClientServerFeed>`
 
 .. include:: includes/background.rst
 .. include:: includes/workspace.rst

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 <https://raw.githubusercontent.com/eProsima/Fast-DDS-Gen/master/resources/Custom.stg>`_
+       A custom template example can be found in this :fastddsgen-raw:`link <resources/Custom.stg>`
    * - -flat-output-dir
      - Ignores input files relative paths and place all generated files in the specified output directory.
    * - -help

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 <https://github.com/eProsima/Fast-DDS/tree/master/examples>`_
-          `GitHub repository <https://github.com/eProsima/Fast-DDS/tree/master/examples>`_.
+          :fastdds-tree:`eProsima Fast DDS <examples>`
+          :fastdds-tree:`GitHub repository <examples>`.
         - ``ON`` ``OFF``
         - ``OFF``
     *   - :class:`INSTALL_EXAMPLES`