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

docs/conf.py

@@ -96,7 +96,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
@@ -110,12 +128,32 @@ def get_git_branch():
         return p.communicate()[0].decode().rstrip()
 
     except Exception:
+<<<<<<< HEAD
         print('Could not get the branch')
+=======
+        # Local build without git or some error occurred
+        print("Could not get the branch")
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
 
     # 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,
@@ -169,6 +207,27 @@ def configure_doxyfile(
     )
 )
 
+# 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:
@@ -208,6 +267,7 @@ def configure_doxyfile(
         fastdds_repo_name,
     )
 
+<<<<<<< HEAD
     # Documentation repository branch
     docs_branch = get_git_branch()
     print('Current documentation branch is "{}"'.format(docs_branch))
@@ -223,6 +283,19 @@ def configure_doxyfile(
     else:
         fastdds_branch = 'origin/2.14.x'
         print(f'Fast DDS branch is not set by env var. Using "{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)
+    else:
+        print(
+            'Fast DDS does not have branch "{}"; falling back to master'.format(
+                fastdds_branch
+            )
+        )
+        fastdds_branch = "origin/master"
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
 
     # Actual checkout
     print('Checking out Fast DDS branch "{}"'.format(fastdds_branch))
@@ -235,6 +308,7 @@ def configure_doxyfile(
         fastdds_python_repo_name,
     )
 
+<<<<<<< HEAD
     # User specified Fast DDS branch
     fastdds_python_branch = os.environ.get('FASTDDS_PYTHON_BRANCH', None)
 
@@ -247,6 +321,19 @@ def configure_doxyfile(
     else:
         fastdds_python_branch = 'origin/1.4.x'
         print(f'Fast DDS Python branch is not set by env var. Using "{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)
+    else:
+        print(
+            'Fast DDS Python does not have branch "{}"; falling back to master'.format(
+                fastdds_python_branch
+            )
+        )
+        fastdds_python_branch = "origin/master"
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
 
     # Actual checkout
     print('Checking out Fast DDS Python branch "{}"'.format(
@@ -315,12 +402,46 @@ def configure_doxyfile(
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+<<<<<<< HEAD
     'breathe',
     'sphinxcontrib.plantuml',
     'sphinx.ext.autodoc',  # Document Pydoc documentation from Python bindings.
     'sphinx_tabs.tabs'
+=======
+    "breathe",
+    "sphinxcontrib.plantuml",
+    "sphinx_copybutton",
+    "sphinx_design",
+    "sphinx.ext.autodoc",  # Document Pydoc documentation from Python bindings.
+    "sphinx.ext.extlinks",
+    "sphinx_substitution_extensions",
+    "sphinx_toolbox.collapse",
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
 ]
 
+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
 
@@ -462,7 +583,51 @@ def configure_doxyfile(
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
+<<<<<<< HEAD
 # html_theme_options = {}
+=======
+html_theme_options = {}
+html_theme_options.update(download_json())
+
+html_use_smartypants = True
+
+# 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

@@ -352,8 +352,14 @@ Full example
 ^^^^^^^^^^^^
 
 The following constitutes a full example on how to configure *server* and *client* both programmatically and using XML.
+<<<<<<< HEAD
 You may also have a look at the *eProsima Fast DDS* Github repository, which contains `an example <https://github.com/eProsima/Fast-DDS/tree/2.x/examples/cpp/dds/DiscoveryServerExample>`_
 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.
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
 
 Server side setup
 """""""""""""""""

docs/fastdds/discovery/static.rst

@@ -67,7 +67,11 @@ 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
+<<<<<<< HEAD
 `Static Discovery example <https://github.com/eProsima/Fast-DDS/blob/2.x/examples/cpp/dds/StaticHelloWorldExample>`_
+=======
+:fastdds-blob:`Static Discovery example <examples/cpp/dds/StaticHelloWorldExample>`
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
 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,8 @@ 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
+<<<<<<< HEAD
 `here <https://github.com/eProsima/Fast-DDS/tree/2.x/examples/cpp/dds>`_.
+=======
+:fastdds-tree:`here <examples/cpp>`.
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))

docs/fastdds/getting_started/simple_python_app/includes/sum_and_next_steps.rst

@@ -9,4 +9,8 @@ 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
+<<<<<<< HEAD
 `here <https://github.com/eProsima/Fast-DDS-python/tree/main/fastdds_python_examples>`_.
+=======
+:fastdds-python-tree:`here <fastdds_python_examples>`.
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))

docs/fastdds/rtps_layer/rtps_layer.rst

@@ -40,9 +40,14 @@ explaining the new features it presents.
 
 We recommend you to look at the two examples describing how to use the RTPS layer that come with the distribution
 while reading this section.
+<<<<<<< HEAD
 They are located in
 `examples/cpp/rtps/AsSocket <https://github.com/eProsima/Fast-DDS/tree/2.x/examples/cpp/rtps/AsSocket>`_ and
 `examples/cpp/rtps/Registered <https://github.com/eProsima/Fast-DDS/tree/2.x/examples/cpp/rtps/Registered>`_
+=======
+It is located in
+:fastdds-tree:`examples/cpp/rtps <examples/cpp/rtps>`.
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
 
 Managing the Participant
 ^^^^^^^^^^^^^^^^^^^^^^^^

docs/fastdds/security/access_control_plugin/access_control_plugin.rst

@@ -110,9 +110,15 @@ The following is an example of the Domain Governance XML file contents.
    :end-before: <!--><-->
    :linenos:
 
+<<<<<<< HEAD
 The `Governance XSD file <https://github.com/eProsima/Fast-DDS/blob/2.x/resources/xsd/governance.xsd>`_ and
 the
 `Governance XML example <https://github.com/eProsima/Fast-DDS/blob/2.x/examples/cpp/dds/SecureHelloWorldExample/certs/governance.xml>`_
+=======
+The :fastdds-blob:`Governance XSD file <resources/xsd/governance.xsd>` and
+the
+:fastdds-blob:`Governance XML example <examples/cpp/dds/SecureHelloWorldExample/certs/governance.xml>`
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
 can also be downloaded from the `eProsima Fast DDS Github repository <https://github.com/eProsima/Fast-DDS>`_.
 
 Domain Rules
@@ -447,9 +453,15 @@ The following is an example of the DomainParticipant Permissions XML file conten
    :end-before: <!--><-->
    :linenos:
 
+<<<<<<< HEAD
 The `Permissions XSD file <https://github.com/eProsima/Fast-DDS/blob/2.x/resources/xsd/governance.xsd>`_ and
 the
 `Permissions XML example <https://github.com/eProsima/Fast-DDS/blob/2.x/examples/cpp/dds/SecureHelloWorldExample/certs/governance.xml>`_
+=======
+The :fastdds-blob:`Permissions XSD file <resources/xsd/governance.xsd>` and
+the
+:fastdds-blob:`Permissions XML example <examples/cpp/dds/SecureHelloWorldExample/certs/governance.xml>`
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
 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

@@ -276,6 +276,13 @@ The examples below show this procedure in both C++ code and XML file.
 HelloWorldExampleSharedMem
 --------------------------
 
+<<<<<<< HEAD
 A Shared Memory version of helloworld example can be found in the
 `HelloWorldExampleSharedMem folder <https://github.com/eProsima/Fast-DDS/tree/2.x/examples/cpp/dds/HelloWorldExampleSharedMem>`_.
 It shows a publisher and a subscriber that communicate through Shared Memory.
+=======
+A hello world example suitable for supported delivery mechanisms can be found in the
+: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).
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))

docs/fastdds/transport/tcp/tcp.rst

@@ -450,7 +450,14 @@ with the **public** IP address and |TCPTransportDescriptor::listening_ports-api|
 HelloWorldExampleTCP
 --------------------
 
+<<<<<<< HEAD
 A TCP version of helloworld example can be found in the
 `HelloWorldExampleTCP folder <https://github.com/eProsima/Fast-DDS/tree/2.x/examples/cpp/dds/HelloWorldExampleTCP>`_.
 It shows a publisher and a subscriber that communicate through TCP.
 The publisher is configured as *TCP server* while the Subscriber is acting as *TCP client*.
+=======
+A hello world example suitable for supported delivery mechanisms can be found in the
+: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).
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))

docs/fastdds/use_cases/request_reply/request_reply.rst

@@ -54,7 +54,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
 ---------------
@@ -152,4 +152,7 @@ For this the client application has to compare the stored |SampleIdentity-api| w
    :start-after: //REQUEST_REPLY_EXAMPLE_CLIENT_RECEIVE_REPLY
    :end-before: //!
 
+<<<<<<< HEAD
 .. _Fast DDS repository: https://github.com/eProsima/Fast-DDS/tree/2.x/examples/cpp/dds/RequestReplyExample
+=======
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))

docs/fastdds/use_cases/statistics_module/statistics_module.rst

@@ -43,7 +43,11 @@ 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:
 
+<<<<<<< HEAD
 * Using the `statistics IDL <https://github.com/eProsima/Fast-DDS/blob/2.x/include/fastdds/statistics/types.idl>`_
+=======
+* Using the :fastdds-blob:`statistics IDL <include/fastdds/statistics/types.idl>`
+>>>>>>> 60e9c7d (Add fallback branch for master links  (#1241))
   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