From 111edc80fafcb5ff3f3e319f5ed6c48da019c124 Mon Sep 17 00:00:00 2001 From: Leander Stephen D'Souza Date: Mon, 11 Aug 2025 03:38:55 +0100 Subject: [PATCH 1/3] Added multiversion support for master. Signed-off-by: Leander Stephen D'Souza --- Makefile | 26 ++++++++ .../otc_tcs_sphinx_theme/static/tcs_theme.css | 64 +++++++++++++++++++ .../otc_tcs_sphinx_theme/static/tcs_theme.js | 52 +++++++++++++++ conf.py | 3 +- requirements.txt | 1 + 5 files changed, 145 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index d5f376abb5..f2152728a4 100644 --- a/Makefile +++ b/Makefile @@ -17,6 +17,7 @@ BUILDDIR = _build DOC_TAG ?= development RELEASE ?= latest PUBLISHDIR = /tmp/navigation2 +SUPPORTED_VERSIONS = master # 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 "" > $(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/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css b/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css index 263df8a775..7b3d72cb95 100644 --- 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 index 6317390701..1363228c21 100644 --- 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']; + 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} ▼`; + + 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 index 64803255fa..18fbddec01 100644 --- 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 index 1cf4fae29e..e577481d7a 100644 --- 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 From 9edd92dd1f00c6a51482a1f05ff6603e24c6521f Mon Sep 17 00:00:00 2001 From: Leander Stephen D'Souza Date: Mon, 11 Aug 2025 06:24:39 +0100 Subject: [PATCH 2/3] Added multiversion command to CircleCI and README. Signed-off-by: Leander Stephen D'Souza --- .circleci/config.yml | 9 ++++++++- README.md | 3 +++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 549f3d3945..43c237601a 100644 --- 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: diff --git a/README.md b/README.md index 9375b678ce..3ba3483129 100644 --- 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). From f6397f765fcfb57311de809fae7bb25dadf1b66b Mon Sep 17 00:00:00 2001 From: Leander Stephen D'Souza Date: Tue, 12 Aug 2025 12:10:02 +0100 Subject: [PATCH 3/3] Added mergify and publishing support for supported branches. Signed-off-by: Leander Stephen D'Souza --- .circleci/config.yml | 6 ++++- .github/mergify.yml | 53 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 .github/mergify.yml diff --git a/.circleci/config.yml b/.circleci/config.yml index 43c237601a..e7224e8214 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -96,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 new file mode 100644 index 0000000000..c206539ce2 --- /dev/null +++ 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}}?