From 1a08487bbceb2b20291a50865c4c5d702adc7a4f Mon Sep 17 00:00:00 2001 From: Elijah Greenstein Date: Fri, 29 May 2026 15:28:49 -0700 Subject: [PATCH 1/2] 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 (cherry picked from commit 52587cb962d2d99333deec67626ce3f4526b8c10) --- 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 db15fa9c8..17bcff08c 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' @@ -75,10 +79,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/ ####################### @@ -205,7 +205,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 649b7ce4ea3e0c1cd29679e19ce0e25dfe70d585 Mon Sep 17 00:00:00 2001 From: Elijah Greenstein Date: Thu, 4 Jun 2026 10:45:45 -0700 Subject: [PATCH 2/2] doc: (temporary) continue RtD build on warnings This commit is intended to temporarily modify Sphinx and Read the Docs settings to support the domain migration to `canonical.com`. - doc/conf.py: A deprecated Sphinx variable, `github_version`, is added to provide for correct "Edit this page" URLs in the built documentation. - doc/.readthedocs.yaml: The `fail_on_warning` variable is set to `false` to allow the use of the deprecated `github_version`. - doc/Makefile: The fail-on-warnings `-W` option is removed. These settings will be restored to their original versions after the documentation has been successfully moved to `canonical.com`. Signed-off-by: Elijah Greenstein --- doc/.readthedocs.yaml | 2 +- doc/Makefile | 2 +- doc/conf.py | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/.readthedocs.yaml b/doc/.readthedocs.yaml index 9bb06942f..568acb6a7 100644 --- a/doc/.readthedocs.yaml +++ b/doc/.readthedocs.yaml @@ -21,7 +21,7 @@ build: sphinx: builder: dirhtml configuration: doc/conf.py - fail_on_warning: true + fail_on_warning: false # If using Sphinx, optionally build your docs in additional formats such as PDF #formats: diff --git a/doc/Makefile b/doc/Makefile index 317a39b4f..ec93a15f6 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -128,7 +128,7 @@ html-rtd: install PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -C integration/lxd/doc/ html-rtd BUILDDIR=$(READTHEDOCS_OUTPUT)/html/lxd PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -C integration/microceph/docs/ html BUILDDIR=$(READTHEDOCS_OUTPUT)/html/microceph PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -C integration/microovn/docs/ html BUILDDIR=$(READTHEDOCS_OUTPUT)/html/microovn - . $(DOCS_VENV); PATH_PREFIX=$(PATH_PREFIX) $(SPHINX_BUILD) -W --keep-going -b dirhtml "$(DOCS_SOURCEDIR)" "$(READTHEDOCS_OUTPUT)/html" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS) + . $(DOCS_VENV); PATH_PREFIX=$(PATH_PREFIX) $(SPHINX_BUILD) --keep-going -b dirhtml "$(DOCS_SOURCEDIR)" "$(READTHEDOCS_OUTPUT)/html" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS) epub: install . $(DOCS_VENV); $(SPHINX_BUILD) -b epub "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS) diff --git a/doc/conf.py b/doc/conf.py index 17bcff08c..9c0252662 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -63,6 +63,7 @@ 'github_url': 'https://github.com/canonical/microcloud', 'repo_default_branch': 'main', 'repo_folder': '/doc/', + 'github_version': 'v2-edge', # Required for feedback button 'github_issues': 'enabled',