Add fallback branch for master links (#1241)

* Add first version of build with master fallback

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

* Minor branch fix

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

* Separate python_branch and python fallback branch

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

* Update repos

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

* Add same fallback logic as in ReadTheDocs checkouts and logs

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

* Changes substitution-block per code-block

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

* Fix refs

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

* Tests with read the docs env variables

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

* Resolving problem when building from RTD

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

* Apply review

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

---------

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

Author: emiliocuestaf

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