Add fallback branch for master links (#1241) (#1251)

* 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>
(cherry picked from commit 60e9c7d)

# Conflicts:
#	docs/conf.py
#	docs/fastdds/discovery/discovery_server.rst
#	docs/fastdds/discovery/static.rst
#	docs/fastdds/getting_started/simple_app/includes/sum_and_next_steps.rst
#	docs/fastdds/getting_started/simple_python_app/includes/sum_and_next_steps.rst
#	docs/fastdds/rtps_layer/rtps_layer.rst
#	docs/fastdds/security/access_control_plugin/access_control_plugin.rst
#	docs/fastdds/transport/shared_memory/shared_memory.rst
#	docs/fastdds/transport/tcp/tcp.rst
#	docs/fastdds/use_cases/request_reply/request_reply.rst
#	docs/fastdds/use_cases/statistics_module/statistics_module.rst
#	docs/fastdds/use_cases/well_known_deployments/well_known_deployments.rst
#	docs/fastdds/use_cases/zero_copy/zero_copy.rst
#	docs/fastdds/xml_configuration/making_xml_profiles.rst
#	docs/fastddsgen/pubsub_app/includes/sum_and_next_steps.rst
#	docs/fastddsgen/rpc_calculator_basic_app/includes/app.rst
#	docs/fastddsgen/rpc_calculator_basic_app/intro.rst
#	docs/fastddsgen/rpc_calculator_feed_app/includes/app.rst
#	docs/fastddsgen/rpc_calculator_feed_app/intro.rst
#	docs/fastddsgen/usage/usage.rst
#	docs/installation/configuration/cmake_options.rst
#	docs/installation/sources/sources_linux.rst
#	docs/installation/sources/sources_mac.rst
#	docs/installation/sources/sources_windows.rst
#	docs/notes/migration_guide.rst
#	docs/notes/previous_versions/v3.0.0.rst

* Fix conflicts

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

* Update ubuntu version in readthedocs.yaml

Signed-off-by: Carlos Ferreira González <carlosferreira@eprosima.com>

* Fix more conflicts, deps, unneeded files

Signed-off-by: Carlos Ferreira González <carlosferreira@eprosima.com>

* Change default branches

Signed-off-by: Carlos Ferreira González <carlosferreira@eprosima.com>

* Adapt version to branch

Signed-off-by: Carlos Ferreira González <carlosferreira@eprosima.com>

* Fix extensions

Signed-off-by: Carlos Ferreira González <carlosferreira@eprosima.com>

* Fix even more conflicts

Signed-off-by: Carlos Ferreira González <carlosferreira@eprosima.com>

---------

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>
Signed-off-by: Carlos Ferreira González <carlosferreira@eprosima.com>
Co-authored-by: Emilio Cuesta Fernandez <emiliocuesta@eprosima.com>
Co-authored-by: Carlos Ferreira González <carlosferreira@eprosima.com>

Author: 3 people

docs/conf.py

@@ -18,22 +18,52 @@
 #
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
+
+import git
+import json
 import os
 import pathlib
+import requests
 import shutil
 import subprocess
 import sys
 
-import git
-
-import requests
-
 
 def setup(app):
     # Add property to avoid warning.
     app.add_config_value('skip_python', None, '')
 
 
+def download_json():
+    """
+    Download the common theme options of eProsima readthedocs documentation.
+
+    The theme options are defined in a JSON file that is hosted in the eProsima GitHub
+    repository with the index of all eProsima product documentation
+    (https://github.com/eProsima/all-docs).
+
+    :return: dictionary.
+    """
+    url = "https://raw.githubusercontent.com/eProsima/all-docs/master/source/_static/json/eprosima-furo.json"
+    ret = dict()
+    try:
+        req = requests.get(url, allow_redirects=True, timeout=10)
+    except requests.RequestException as e:
+        print(
+            "Failed to download the JSON with the eProsima theme."
+            "Request Error: {}".format(e)
+        )
+        return ret
+    if req.status_code != 200:
+        print(
+            "Failed to download the JSON with the eProsima theme."
+            "Return code: {}".format(req.status_code)
+        )
+        return ret
+    ret = json.loads(req.content)
+    return ret
+
+
 def download_css(html_css_dir):
     """
     Download the common theme of eProsima readthedocs documentation.
@@ -96,7 +126,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 +158,28 @@ def get_git_branch():
         return p.communicate()[0].decode().rstrip()
 
     except Exception:
-        print('Could not get the branch')
+        # 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,
@@ -169,6 +233,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, "2.14.x")
+fastdds_docs_fallback_branch = resolve_fallback_branch("FASTDDS_DOCS_BRANCH", docs_branch, "2.14.x")
+fastdds_python_fallback_branch = resolve_fallback_branch("FASTDDS_PYTHON_BRANCH", docs_branch, "1.4.x")
+fastdds_gen_fallback_branch = resolve_fallback_branch("FASTDDS_GEN_BRANCH", docs_branch, "3.3.x")
+
+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,21 +293,17 @@ 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 checkout to 2.14.x
-    if (fastdds_branch and
-            fastdds.refs.__contains__('origin/{}'.format(fastdds_branch))):
-        fastdds_branch = 'origin/{}'.format(fastdds_branch)
+    # Verify the desired branch actually exists in the cloned remote, falling back to 2.14.x if not.
+    fastdds_branch = fastdds_fallback_branch
+    if fastdds.refs.__contains__("origin/{}".format(fastdds_branch)):
+        fastdds_branch = "origin/{}".format(fastdds_branch)
     else:
-        fastdds_branch = 'origin/2.14.x'
-        print(f'Fast DDS branch is not set by env var. Using "{fastdds_branch}"')
+        print(
+            'Fast DDS does not have branch "{}"; falling back to 2.14.x'.format(
+                fastdds_branch
+            )
+        )
+        fastdds_branch = "origin/2.14.x"
 
     # Actual checkout
     print('Checking out Fast DDS branch "{}"'.format(fastdds_branch))
@@ -235,18 +316,17 @@ 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 checkout to 1.4.x
-    if (fastdds_python_branch and
-            fastdds_python.refs.__contains__(
-                'origin/{}'.format(fastdds_python_branch))):
-        fastdds_python_branch = 'origin/{}'.format(fastdds_python_branch)
+    # Verify the desired branch actually exists in the cloned remote, falling back to 2.14.x 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:
-        fastdds_python_branch = 'origin/1.4.x'
-        print(f'Fast DDS Python branch is not set by env var. Using "{fastdds_python_branch}"')
+        print(
+            'Fast DDS Python does not have branch "{}"; falling back to 2.14.x'.format(
+                fastdds_python_branch
+            )
+        )
+        fastdds_python_branch = "origin/2.14.x"
 
     # Actual checkout
     print('Checking out Fast DDS Python branch "{}"'.format(
@@ -315,12 +395,40 @@ def configure_doxyfile(
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'breathe',
-    'sphinxcontrib.plantuml',
-    'sphinx.ext.autodoc',  # Document Pydoc documentation from Python bindings.
-    'sphinx_tabs.tabs'
+    "breathe",
+    "sphinx_copybutton",
+    "sphinx_design",
+    "sphinx_substitution_extensions",
+    "sphinx_tabs.tabs",
+    "sphinx_toolbox.collapse",
+    "sphinx.ext.autodoc",  # Document Pydoc documentation from Python bindings.
+    "sphinx.ext.extlinks",
+    "sphinxcontrib.plantuml",
 ]
 
+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 +570,12 @@ def configure_doxyfile(
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {}
+html_theme_options.update(download_json())
+
+html_use_smartypants = True
+
+html_css_files = [select_css(script_path)]
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

docs/fastdds/discovery/discovery_server.rst

@@ -352,8 +352,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/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.
 
 Server side setup
 """""""""""""""""

docs/fastdds/discovery/static.rst

@@ -67,7 +67,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/2.x/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/2.x/examples/cpp/dds>`_.
+: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/main/fastdds_python_examples>`_.
+:fastdds-python-tree:`here <fastdds_python_examples>`.

docs/fastdds/rtps_layer/rtps_layer.rst

@@ -41,8 +41,7 @@ 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.
 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>`_
+:fastdds-tree:`examples/cpp/rtps <examples/cpp/rtps>`.
 
 Managing the Participant
 ^^^^^^^^^^^^^^^^^^^^^^^^

docs/fastdds/security/access_control_plugin/access_control_plugin.rst

@@ -110,9 +110,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/2.x/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/2.x/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
@@ -447,9 +447,8 @@ 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/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>`
 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,7 @@ The examples below show this procedure in both C++ code and XML file.
 HelloWorldExampleSharedMem
 --------------------------
 
-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).

docs/fastdds/transport/tcp/tcp.rst

@@ -451,6 +451,7 @@ HelloWorldExampleTCP
 --------------------
 
 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>`_.
+:fastdds-tree:`HelloWorld TCP Example <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*.
+:fastdds-blob:`Static Discovery example <examples/cpp/dds/StaticHelloWorldExample>`

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
 ---------------
@@ -151,5 +151,3 @@ For this the client application has to compare the stored |SampleIdentity-api| w
    :dedent: 4
    :start-after: //REQUEST_REPLY_EXAMPLE_CLIENT_RECEIVE_REPLY
    :end-before: //!
-
-.. _Fast DDS repository: https://github.com/eProsima/Fast-DDS/tree/2.x/examples/cpp/dds/RequestReplyExample