From 1b3eb8aff5b48e7b8d1559d22cbf90868ac6f70b Mon Sep 17 00:00:00 2001 From: Elijah Greenstein Date: Fri, 29 May 2026 15:28:49 -0700 Subject: [PATCH 1/3] doc: update conf.py and add js for URL migration These changes support migration of the documentation from documentation.ubuntu.com/microcloud to canonical.com/microcloud/docs: - Adds `doc/_static/js/overwrite_links.js` to properly handle links in the flyout menu (version selector). - Updates configuration settings in `doc/conf.py` - Reorganizes JavaScript files into `doc/_static/js` directory, and updates relevant paths Signed-off-by: Elijah Greenstein --- doc/_static/js/overwrite_links.js | 38 +++++++++++++++++++++ doc/_static/{ => js}/rtd-versions-flyout.js | 0 doc/conf.py | 19 ++++++----- 3 files changed, 48 insertions(+), 9 deletions(-) create mode 100644 doc/_static/js/overwrite_links.js rename doc/_static/{ => js}/rtd-versions-flyout.js (100%) diff --git a/doc/_static/js/overwrite_links.js b/doc/_static/js/overwrite_links.js new file mode 100644 index 000000000..c23cdb11a --- /dev/null +++ b/doc/_static/js/overwrite_links.js @@ -0,0 +1,38 @@ + // Replace oldDomain with newDomain + const oldDomain = 'canonical-microcloud-documentation.readthedocs-hosted.com'; + const newDomain = 'canonical.com/microcloud/docs'; + + function escapeRegExp(value) { + return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); + } + + function overwriteMatchingAnchorUrls(container) { + if (!container) return; + + const anchors = container.querySelectorAll('a[href], link[href]'); + const oldDomainRegex = new RegExp(escapeRegExp(oldDomain), 'g'); + + anchors.forEach(anchor => { + anchor.href = anchor.href.replace(oldDomainRegex, newDomain); + }); + } + + overwriteMatchingAnchorUrls(document.querySelector('header')); + + // Use a MutationObserver to wait for the RTD flyout element to appear in the DOM + const observer = new MutationObserver(function(mutations, obs) { + + const rtdFlyout = document.querySelector('readthedocs-flyout'); + if (!rtdFlyout) return; + + obs.disconnect(); + + rtdFlyout.addEventListener('click', function() { + const shadowRoot = rtdFlyout.shadowRoot; + if (!shadowRoot) return; + + overwriteMatchingAnchorUrls(shadowRoot); + }); + }); + + observer.observe(document.body, { childList: true, subtree: true }); diff --git a/doc/_static/rtd-versions-flyout.js b/doc/_static/js/rtd-versions-flyout.js similarity index 100% rename from doc/_static/rtd-versions-flyout.js rename to doc/_static/js/rtd-versions-flyout.js diff --git a/doc/conf.py b/doc/conf.py index 35739352c..2503b8ce5 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -32,14 +32,18 @@ # Copyright string; shown at the bottom of the page copyright = '2014-%s AGPL-3.0, %s' % (datetime.date.today().year, author) -# Use RTD canonical URL to ensure duplicate pages have a single canonical URL -# that includes the version (such as /latest/); helps SEO. -html_baseurl = os.environ.get('READTHEDOCS_CANONICAL_URL', '/') +# Documentation website URL + +version_slug = f'{os.environ.get("READTHEDOCS_VERSION", "local")}' + +slug = 'microcloud/docs' + +html_baseurl = f'https://canonical.com/microcloud/docs/{version_slug}/' # OpenGraph metadata used for social sharing previews ogp_site_url = html_baseurl ogp_site_name = html_title -ogp_image = 'https://documentation.ubuntu.com/microcloud/latest/_static/microcloud_tag.png' +ogp_image = f'https://canonical.com/microcloud/docs/{version_slug}/_static/microcloud_tag.png' html_favicon = '_static/favicon.png' @@ -77,10 +81,6 @@ 'source_edit_link': html_context['github_url'] } -# Project slug -# Required if your project is hosted on documentation.ubuntu.com -slug = 'microcloud' - ####################### # Sitemap configuration: https://sphinx-sitemap.readthedocs.io/ ####################### @@ -211,7 +211,8 @@ html_js_files = [ 'https://assets.ubuntu.com/v1/287a5e8f-bundle.js', - 'rtd-versions-flyout.js', + 'js/rtd-versions-flyout.js', + "js/overwrite_links.js", ] # Feedback button at the top; enabled by default From 0d716bdd2151af439bc84cb05787be4355f8a124 Mon Sep 17 00:00:00 2001 From: Elijah Greenstein Date: Thu, 4 Jun 2026 20:51:15 -0700 Subject: [PATCH 2/3] doc/conf.py: temporarily remove "edit page" button This commit removes the "Contribute to this page" button. This change is temporary, and the button will be restored after the docs have moved to canonical.com. Signed-off-by: Elijah Greenstein --- doc/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 2503b8ce5..d579491fd 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -77,9 +77,9 @@ html_extra_path = ['_extra'] # Enables the pencil icon to edit pages on GitHub, shown at the top of each page -html_theme_options = { - 'source_edit_link': html_context['github_url'] -} +# html_theme_options = { +# 'source_edit_link': html_context['github_url'] +# } ####################### # Sitemap configuration: https://sphinx-sitemap.readthedocs.io/ From c8ce384f83b01a360e705d9094bf63cf2f6a30db Mon Sep 17 00:00:00 2001 From: Elijah Greenstein Date: Thu, 25 Jun 2026 11:54:57 -0700 Subject: [PATCH 3/3] doc: only use MicroCloud overwrite_links.js Signed-off-by: Elijah Greenstein --- doc/Makefile | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 61a6e49a5..c5e512091 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -96,7 +96,7 @@ integrate: mkdir -p integration/microcloud/_templates/ integration/microcloud/_static mkdir -p integration/microceph/docs/_templates integration/microceph/docs/_static - # Copy the header HTML and CSS files for the doc sets + # Copy the header HTML and CSS files for the doc sets cp .sphinx/_integration/microcloud.html integration/microcloud/_templates/header.html cp .sphinx/_integration/override-header.css integration/microcloud/_static/ cp .sphinx/_integration/lxd.html integration/lxd/doc/_templates/header.html @@ -106,6 +106,9 @@ integrate: cp .sphinx/_integration/microovn.html integration/microovn/docs/.sphinx/_templates/header.html cp .sphinx/_integration/header.css integration/microovn/docs/.sphinx/_static/ + # Copy the JavaScript to overwrite links + cp _static/js/overwrite_links.js integration/lxd/doc/_static/js/overwrite_links.js + # Add information about where to find the tags/docs to the doc sets cat .sphinx/_integration/add_config.py >> integration/lxd/doc/conf.py cat .sphinx/_integration/add_config.py >> integration/microceph/docs/conf.py @@ -230,4 +233,4 @@ spellcheck: spelling # "make mode" option. $(O) is meant as a shortcut for $(SPHINX_OPTS). %: $(MAKE) --no-print-directory install - . $(DOCS_VENV); $(SPHINX_BUILD) -M $@ "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) $(O) \ No newline at end of file + . $(DOCS_VENV); $(SPHINX_BUILD) -M $@ "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) $(O)