[24299] Add fallback branch for master links (backport #1241)

docs/conf.py

@@ -207,7 +207,25 @@ def select_css(html_css_dir):
 
 
 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
@@ -229,12 +247,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,
@@ -282,6 +316,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:
@@ -314,6 +369,7 @@ def configure_doxyfile(
         fastdds_repo_name,
     )
 
+<<<<<<< HEAD
     # Documentation repository branch
     docs_branch = get_git_branch()
     print('Current documentation branch is "{}"'.format(docs_branch))
@@ -325,13 +381,16 @@ def configure_doxyfile(
     # Else try with current documentation branch
     # Else checkout to 3.2.x
     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)):
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
         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/3.2.x"
@@ -347,6 +406,7 @@ def configure_doxyfile(
         fastdds_python_repo_name,
     )
 
+<<<<<<< HEAD
     # User specified Fast DDS branch
     fastdds_python_branch = os.environ.get("FASTDDS_PYTHON_BRANCH", None)
 
@@ -356,15 +416,16 @@ def configure_doxyfile(
     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)):
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
         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/2.2.x"
@@ -444,9 +505,37 @@ def configure_doxyfile(
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx.ext.autodoc",  # Document Pydoc documentation from Python bindings.
+<<<<<<< HEAD
+=======
+    "sphinx.ext.extlinks",
+    "sphinx_substitution_extensions",
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
     "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
 
@@ -611,7 +700,46 @@ def configure_doxyfile(
 
 html_use_smartypants = True
 
+<<<<<<< HEAD
 html_css_files = [select_css(script_path)]
+=======
+# The CSS files referenced here should have a path relative to the _static folder.
+# We use static_relative(download_file(...)) to ensure the resulting paths are relative to "_static".
+html_css_files = [
+    static_relative(
+        download_file(
+            "https://raw.githubusercontent.com/eProsima/all-docs/master/source/_static/css/eprosima-furo.css",
+            "{}/_static/css/eprosima-furo.css".format(script_path),
+        )
+    ),
+    static_relative(
+        download_file(
+            "https://raw.githubusercontent.com/eProsima/all-docs/master/source/_static/css/pro-badge.css",
+            "{}/_static/css/pro-badge.css".format(script_path),
+        )
+    ),
+]
+
+# Custom substitutions that are included at the beginning of every source file.
+# |Pro|: badge with PRO text. Place it after titles where needed as follows:
+#    Title |Pro|
+#    ===========
+# rst_prolog = r"""
+# .. |Pro| replace:: :bdg-primary-line:`Pro`
+# """
+rst_prolog = f"""
+.. |Pro| raw:: html
+
+    <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}
+"""
+
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

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.