doc: update conf.py and add js for URL migration (v2-edge)

doc/.sphinx/_integration/add_config.py

@@ -12,6 +12,7 @@
 if project == "LXD":
     html_baseurl = "https://canonical.com/lxd/docs/v5.21/"
     html_css_files = globals().get('html_css_files', []) + ['override-header.css']
+    html_js_files = globals().get('html_js_files', []) + ['js/overwrite_microcloud_links.js']
     tags.add('integrated')
 elif project == "MicroCeph":
     html_baseurl = "https://documentation.ubuntu.com/canonical-microceph/v19.2.0-squid/"
@@ -20,9 +21,13 @@
     # Override default header styles
     html_static_path = globals().get('html_static_path', []) + ["_static"]
     html_css_files = globals().get('html_css_files', []) + ['override-header.css']
+    # Add js to overwrite MicroCloud links
+    html_js_files = globals().get('html_js_files', []) + ['overwrite_microcloud_links.js']
     # Add "integrated" to the list of custom tags
     tags.add('integrated')
 elif project == "MicroOVN":
     html_baseurl = "https://ubuntu.com/docs/microovn/24.03/"
-    custom_tags.append('integrated')
-
+    tags.add('integrated')
+    html_static_path = globals().get('html_static_path', []) + ["_static"]
+    # Add js to overwrite MicroCloud links
+    html_js_files = globals().get('html_js_files', []) + ['overwrite_microcloud_links.js']

doc/Makefile

@@ -109,11 +109,18 @@ integrate:
 	# 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
-	cat .sphinx/_integration/add_config.py >> integration/microovn/docs/custom_conf.py
+	cat .sphinx/_integration/add_config.py >> integration/microovn/docs/conf.py
 
 	# Override the MicroOVN tag with the circle of friends one (for consistency)
 	cp .sphinx/_integration/tag.png integration/microovn/docs/.sphinx/_static/microovn.png
 
+	# Copy MicroCloud `overwrite_links.js` to all repos
+	cp _static/js/overwrite_links.js integration/lxd/doc/_static/js/overwrite_microcloud_links.js
+	mkdir -p integration/microceph/docs/_static
+	cp _static/js/overwrite_links.js integration/microceph/docs/_static/overwrite_microcloud_links.js
+	mkdir -p integration/microovn/docs/_static
+	cp _static/js/overwrite_links.js integration/microovn/docs/_static/overwrite_microcloud_links.js
+
 # `html` builds the integrated docs.
 html: integrate install
 	mkdir -p $(current_dir)/_build

doc/_static/js/overwrite_links.js

@@ -0,0 +1,38 @@
+ // Replace oldDomain with newDomain
+ const microcloud_oldDomain = 'canonical-microcloud-documentation.readthedocs-hosted.com';
+ const microcloud_newDomain = 'canonical.com/microcloud/docs';
+
+ function microcloud_escapeRegExp(value) {
+     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ }
+
+ function microcloud_overwriteMatchingAnchorUrls(container) {
+     if (!container) return;
+
+     const anchors = container.querySelectorAll('a[href], link[href]');
+     const oldDomainRegex = new RegExp(microcloud_escapeRegExp(microcloud_oldDomain), 'g');
+
+     anchors.forEach(anchor => {
+         anchor.href = anchor.href.replace(oldDomainRegex, microcloud_newDomain);
+     });
+ }
+
+ microcloud_overwriteMatchingAnchorUrls(document.querySelector('header'));
+
+ // Use a MutationObserver to wait for the RTD flyout element to appear in the DOM
+ const microcloud_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;
+
+         microcloud_overwriteMatchingAnchorUrls(shadowRoot);
+     });
+ });
+
+ microcloud_observer.observe(document.body, { childList: true, subtree: true });

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'
 
@@ -71,13 +75,9 @@
 }
 
 # 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']
-}
-
-# Project slug
-# Required if your project is hosted on documentation.ubuntu.com
-slug = 'microcloud'
+# html_theme_options = {
+#     'source_edit_link': html_context['github_url']
+# }
 
 #######################
 # 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