ros-navigation · leander-dsouza · Aug 11, 2025 · Aug 11, 2025 · Aug 12, 2025 · Aug 11, 2025
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -20,10 +20,16 @@ references:
           python3-pip \
           ttf-dejavu
         pip3 install -r requirements.txt
-  make_docs: &make_docs
+  make_local_docs: &make_local_docs
     run:
+      name: Build local docs
       command: |
         make html
+  make_docs: &make_docs
+    run:
+      name: Build multiversion docs
+      command: |
+        make clean multiversion
   store_docs: &store_docs
     store_artifacts:
         path: _build/html
@@ -45,6 +51,7 @@ commands:
   build_docs:
     description: "Build docs"
     steps:
+      - *make_local_docs
       - *make_docs
       - *store_docs
   publish_docs_to_gh_pages_branch:
@@ -89,4 +96,8 @@ workflows:
             - docs_build
           filters:
             branches:
-              only: master
+              only:
+                - master
+                - kilted
+                - jazzy
+                - humble
diff --git a/.github/mergify.yml b/.github/mergify.yml
@@ -0,0 +1,53 @@
+pull_request_rules:
+
+  - name: backport at reviewers discretion
+    conditions:
+      - base=master
+      - "label=backport-all"
+    actions:
+      backport:
+        branches:
+          - kilted
+          - jazzy
+          - humble
+
+  - name: backport to kilted at reviewers discretion
+    conditions:
+      - base=master
+      - "label=backport-kilted"
+    actions:
+      backport:
+        branches:
+          - kilted
+
+  - name: backport to jazzy at reviewers discretion
+    conditions:
+      - base=master
+      - "label=backport-jazzy"
+    actions:
+      backport:
+        branches:
+          - jazzy
+
+  - name: backport to humble at reviewers discretion
+    conditions:
+      - base=master
+      - "label=backport-humble"
+    actions:
+      backport:
+        branches:
+          - humble
+
+  - name: delete head branch after merge
+    conditions:
+      - merged
+    actions:
+      delete_head_branch:
+
+  - name: ask to resolve conflict
+    conditions:
+      - conflict
+      - author!=mergify
+    actions:
+        comment:
+          message: This pull request is in conflict. Could you fix it @{{author}}?
diff --git a/Makefile b/Makefile
@@ -17,6 +17,7 @@ BUILDDIR      = _build
 DOC_TAG      ?= development
 RELEASE      ?= latest
 PUBLISHDIR    = /tmp/navigation2
+SUPPORTED_VERSIONS = master kilted
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -35,6 +36,31 @@ help:
 html:
 	$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O)
 
+multiversion:
+	@(\
+	if ! git diff-index --quiet HEAD --; then \
+		git stash push -q -m "multiversion build temporary stash"; \
+		echo "Changes stashed"; \
+	fi; \
+	)
+	@(\
+	original_branch=$$(git symbolic-ref --short HEAD); \
+	echo "Building documentation for supported versions: $(SUPPORTED_VERSIONS)"; \
+	for version in $(SUPPORTED_VERSIONS); do \
+		echo "Building $$version..."; \
+		git checkout -q $$version && \
+		$(SPHINXBUILD) -b html $(SPHINXOPTS) . $(BUILDDIR)/html/$$version || exit 1; \
+	done; \
+	git checkout -q $$original_branch; \
+	echo "<html><head><meta http-equiv=\"refresh\" content=\"0; url=master/index.html\" /></head></html>" > $(BUILDDIR)/html/index.html \
+	)
+	@(\
+	if git stash list | grep -q "multiversion build temporary stash"; then \
+		git stash pop -q; \
+		echo "Changes restored from stash"; \
+	fi \
+	)
+
 # Autobuild the docs on changes
 
 autobuild:

diff --git a/README.md b/README.md
@@ -33,6 +33,9 @@ pip3 install -r requirements.txt
 ### Build the Docs
 Build the docs locally with `make html` and you'll find the built docs entry point in `_build/html/index.html`.
 
+For building the deployed version of the docs, `make multiversion` will build the documentation for all supported branches of Nav2, ignoring the changes locally.
+To include your local changes, make sure to merge locally with the supported branch you want to build against.
+
 Any images, diagrams, or videos are subject to their own copyrights, trademarks, and licenses.
 
 Want a local PDF version? Follow the [instructions here](https://gist.github.com/alfredodeza/7fb5c667addb1c6963b9).
diff --git a/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css b/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css
@@ -170,3 +170,67 @@ th,td {
     display: inline;
     margin-left: 20px;
 }
+
+/* Version dropdown styles */
+.version-dropdown {
+    position: relative;
+    display: inline-block;
+    width: 100%;
+    margin-bottom: 20px;
+    border: 2px solid #ccc;
+    border-radius: 4px;
+}
+
+.version-btn {
+    background-color: #2980b9;
+    color: white;
+    padding: 10px 15px;
+    font-size: 16px;
+    border: none;
+    cursor: pointer;
+    width: 100%;
+    text-align: left;
+    border-radius: 4px;
+    font-family: inherit;
+}
+
+.version-btn:hover {
+    background-color: #3498db;
+}
+
+.version-caret {
+    float: right;
+}
+
+.version-dropdown-content {
+    display: none;
+    position: absolute;
+    background-color: #f9f9f9;
+    min-width: 160px;
+    box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2);
+    z-index: 1;
+    width: 100%;
+    border-radius: 4px;
+    overflow: hidden;
+    text-align: left;
+}
+
+.version-dropdown-content a {
+    color: #333;
+    padding: 12px 16px;
+    text-decoration: none;
+    display: block;
+    background-color: #f9f9f9;
+}
+
+.version-dropdown-content a:hover {
+    background-color: #ddd;
+}
+
+.version-dropdown-content.show {
+    display: block;
+}
+
+.wy-side-nav-search {
+    margin-top: 0;
+}
diff --git a/_themes/otc_tcs_sphinx_theme/static/tcs_theme.js b/_themes/otc_tcs_sphinx_theme/static/tcs_theme.js
@@ -48,3 +48,55 @@ for (i = 0; i < contents.length; i++) {
     }
   }
 }
+
+document.addEventListener('DOMContentLoaded', function() {
+    const supportedVersions = ['rolling', 'kilted'];
+    const versionDropdown = document.createElement('div');
+    versionDropdown.className = 'version-dropdown';
+
+    // Detect current version from URL
+    const currentVersion = supportedVersions.find(version =>
+        window.location.pathname.includes(`/${version}/`)
+    ) || 'rolling'; // Default to rolling if none found
+
+    const dropdownBtn = document.createElement('button');
+    dropdownBtn.className = 'version-btn';
+    dropdownBtn.innerHTML = `${currentVersion} <span class="version-caret">▼</span>`;
+
+    const dropdownContent = document.createElement('div');
+    dropdownContent.className = 'version-dropdown-content';
+
+    supportedVersions.forEach(version => {
+        const link = document.createElement('a');
+
+        // Replace current version in path with selected version
+        const newPath = window.location.pathname.replace(
+            new RegExp(`/(${supportedVersions.join('|')})/`),
+            `/${version}/`
+        );
+
+        link.href = newPath;
+        link.textContent = version;
+        dropdownContent.appendChild(link);
+    });
+
+    versionDropdown.appendChild(dropdownBtn);
+    versionDropdown.appendChild(dropdownContent);
+
+    const searchBox = document.querySelector('.wy-side-nav-search');
+    const logo = document.querySelector('.wy-side-nav-search > a');
+
+    if (searchBox && logo) {
+        searchBox.insertBefore(versionDropdown, logo.nextSibling);
+    }
+    // Toggle dropdown
+    dropdownBtn.addEventListener('click', function(e) {
+        e.stopPropagation();
+        dropdownContent.classList.toggle('show');
+    });
+
+    // Close dropdown when clicking outside
+    document.addEventListener('click', function() {
+        dropdownContent.classList.remove('show');
+    });
+});
diff --git a/conf.py b/conf.py
@@ -39,6 +39,7 @@
     'sphinx.ext.extlinks',
     'sphinx.ext.graphviz',
     'sphinxcontrib.plantuml',
+    'sphinx_multiversion',
 ]
 
 myst_enable_extensions = ['colon_fence']
@@ -124,7 +125,7 @@
         'canonical_url': '',
         'analytics_id': 'G-EVD5Z6G6NH',
         'logo_only': False,
-        'display_version': True,
+        'display_version': False,
         'prev_next_buttons_location': 'None',
         # Toc options
         'collapse_navigation': False,

diff --git a/requirements.txt b/requirements.txt
@@ -7,3 +7,4 @@ sphinx_rtd_theme==2.0.0
 sphinx-autobuild
 sphinx==5.3.0
 sphinxcontrib-plantuml
+sphinx-multiversion