docs: migrate docs hosting site to ubuntu.com/docs (Infra)

docs/.sphinx/_static/overwrite_links.js

@@ -0,0 +1,52 @@
+// Replaces rtd-address with new-address in links
+
+const rtd_address = 'canonical-checkbox.readthedocs-hosted.com';
+const new_address = 'ubuntu.com/docs/checkbox';
+
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function overwriteMatchingAnchorUrls(container) {
+    if (!container) return;
+
+    const rtd_addressRegex = new RegExp(escapeRegExp(rtd_address), 'g');
+    container.querySelectorAll('a[href], link[href]').forEach((anchor) => {
+        anchor.href = anchor.href.replace(rtd_addressRegex, new_address);
+    });
+}
+
+function patchFlyout() {
+    const rtdFlyout = document.querySelector('readthedocs-flyout');
+    if (!rtdFlyout) return false;
+
+    overwriteMatchingAnchorUrls(rtdFlyout);
+    overwriteMatchingAnchorUrls(rtdFlyout.shadowRoot);
+
+    rtdFlyout.addEventListener('click', () => {
+        overwriteMatchingAnchorUrls(rtdFlyout);
+        overwriteMatchingAnchorUrls(rtdFlyout.shadowRoot);
+    });
+
+    return true;
+}
+
+function init() {
+    overwriteMatchingAnchorUrls(document.querySelector('header'));
+
+    if (patchFlyout()) return;
+
+    const observer = new MutationObserver(() => {
+        if (patchFlyout()) {
+            observer.disconnect();
+        }
+    });
+
+    observer.observe(document.body, { childList: true, subtree: true });
+}
+
+if (document.body) {
+    init();
+} else {
+    document.addEventListener('DOMContentLoaded', init);
+}

docs/.sphinx/_templates/footer.html

@@ -0,0 +1,103 @@
+<div class="related-pages">
+  {# mod: Per-page navigation #}
+  {% if meta %}
+    {% if 'sequential_nav' in meta %}
+      {% set sequential_nav = meta.sequential_nav %}
+    {% endif %}
+  {% endif %}
+  {# mod: Conditional wrappers to control page navigation buttons #}
+  {% if sequential_nav != "none" -%}
+    {% if next and (sequential_nav == "next" or sequential_nav == "both") -%}
+      <a class="next-page" href="{{ next.link }}">
+        <div class="page-info">
+          <div class="context">
+            <span>{{ _("Next") }}</span>
+          </div>
+          <div class="title">{{ next.title }}</div>
+        </div>
+        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+      </a>
+    {%- endif %}
+    {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%}
+      <a class="prev-page" href="{{ prev.link }}">
+        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+        <div class="page-info">
+          <div class="context">
+            <span>{{ _("Previous") }}</span>
+          </div>
+          {% if prev.link == pathto(root_doc) %}
+            <div class="title">{{ _("Home") }}</div>
+          {% else %}
+            <div class="title">{{ prev.title }}</div>
+          {% endif %}
+        </div>
+      </a>
+    {%- endif %}
+  {%- endif %}
+</div>
+<div class="bottom-of-page">
+  <div class="left-details">
+    {%- if show_copyright %}
+    <div class="copyright">
+      {%- if hasdoc('copyright') %}
+        {% trans path=pathto('copyright'), copyright=copyright|e -%}
+          <a href="{{ path }}">&copy; {{ copyright }} {{ author }}</a>
+        {%- endtrans %}
+      {%- else %}
+        {% trans copyright=copyright|e -%}
+          &copy; {{ copyright }} {{ author }}
+        {%- endtrans %}
+      {%- endif %}
+    </div>
+    {%- endif %}
+    {%- if license and license.name -%}
+      {%- if license.url -%}
+      <div class="license">
+        This page is licensed under <a href="{{ license.url }}">{{ license.name }}</a>
+      </div>
+      {%- else -%}
+      <div class="license">
+        This page is licensed under {{ license.name }}
+      </div>
+      {%- endif -%}
+    {%- endif -%}
+
+    {# mod: removed "Made with" #}
+
+    {%- if last_updated -%}
+    <div class="last-updated">
+      {% trans last_updated=last_updated|e -%}
+        Last updated on {{ last_updated }}
+      {%- endtrans -%}
+    </div>
+    {%- endif %}
+
+    {%- if show_source and has_source and sourcename %}
+    <div class="show-source">
+      <a class="muted-link" href="{{ pathto('_sources/' + sourcename, true)|e }}"
+         rel="nofollow">Show source</a>
+    </div>
+    {%- endif %}
+  </div>
+  <div>
+   {% if has_contributor_listing and display_contributors and pagename and page_source_suffix %}
+       {% set contributors = get_contributors_for_file(pagename, page_source_suffix) %}
+       {% if contributors %}
+          {% if contributors | length > 1 %}
+              <a class="display-contributors">Thanks to the {{ contributors |length }} contributors!</a>
+          {% else %}
+              <a class="display-contributors">Thanks to our contributor!</a>
+          {% endif %}
+          <div id="overlay"></div>
+          <ul class="all-contributors">
+              {% for contributor in contributors %}
+                  <li>
+                      <a href="{{ contributor[1] }}" class="contributor">{{ contributor[0] }}</a>
+                  </li>
+              {% endfor %}
+          </ul>
+       {% endif %}
+   {% endif %}
+  </div>
+  <div class="right-details"><a href="" class="js-revoke-cookie-manager muted-link">Manage your tracker settings</a></div>
+</div>

docs/.sphinx/_templates/header.html

@@ -0,0 +1,72 @@
+<header id="header" class="p-navigation">
+
+  <!-- Google Tag Manager -->
+  <script>
+    (function(w, d, s, l, i) {
+      w[l] = w[l] || [];
+      w[l].push({
+        'gtm.start': new Date().getTime(),
+        event: 'gtm.js'
+      });
+      var f = d.getElementsByTagName(s)[0];
+      var j = d.createElement(s);
+      var dl = '';
+      if (l != 'dataLayer') {
+          dl = '&l=' + l;
+      }
+      j.async = true;
+      j.src = 'https://www.googletagmanager.com/gtm.js?id=' + i + dl;
+      f.parentNode.insertBefore(j, f);
+    })(window, document, 'script', 'dataLayer', 'GTM-KNX3CJC');
+  </script>
+
+  <div class="p-navigation__nav" role="menubar">
+
+    <ul class="p-navigation__links" role="menu">
+
+      <li>
+        <a class="p-logo" href="https://{{ product_page }}" aria-current="page">
+          <img src="{{ pathto(product_tag,1) }}" alt="Logo" class="p-logo-image">
+          <div class="p-logo-text p-heading--4">{{ project }}
+          </div>
+        </a>
+      </li>
+
+      <li class="nav-ubuntu-com">
+        <a href="https://{{ product_page }}" class="p-navigation__link">{{ product_page }}</a>
+      </li>
+
+      <li>
+        <a href="#" class="p-navigation__link nav-more-links">More resources</a>
+        <ul class="more-links-dropdown">
+
+          {% if discourse %}
+          <li>
+            <a href="{{ discourse }}" class="p-navigation__sub-link p-dropdown__link">Discourse</a>
+          </li>
+          {% endif %}
+
+          {% if mattermost %}
+          <li>
+            <a href="{{ mattermost }}" class="p-navigation__sub-link p-dropdown__link">Mattermost</a>
+          </li>
+          {% endif %}
+
+          {% if matrix %}
+          <li>
+            <a href="{{ matrix }}" class="p-navigation__sub-link p-dropdown__link">Matrix</a>
+          </li>
+          {% endif %}
+
+          {% if github_url %}
+          <li>
+            <a href="{{ github_url }}" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
+          </li>
+          {% endif %}
+
+        </ul>
+      </li>
+
+    </ul>
+  </div>
+</header>

docs/conf.py

@@ -68,7 +68,7 @@
 # NOTE: The Open Graph Protocol (OGP) enhances page display in a social graph
 #       and is used by social media platforms; see https://ogp.me/
 
-ogp_site_url = "https://canonical-checkbox.readthedocs-hosted.com/latest/"
+ogp_site_url = f"https://ubuntu.com/docs/checkbox/{os.environ.get('READTHEDOCS_VERSION', 'local')}/"
 
 # Preview name of the documentation website
 ogp_site_name = project
@@ -149,24 +149,25 @@
 # - https://launchpad.net/example
 # - https://git.launchpad.net/example
 #
-# html_theme_options = {
-# 'source_edit_link': 'https://github.com/canonical/sphinx-docs-starter-pack',
-# }
+html_theme_options = {
+    "source_edit_link": "https://github.com/canonical/checkbox",
+}
 
 # Project slug; see https://meta.discourse.org/t/what-is-category-slug/87897
 #
 # TODO: If your documentation is hosted on https://docs.ubuntu.com/,
 #       uncomment and update as needed.
 
-# slug = ''
+slug = "docs/checkbox"  # required when hosted on ubuntu.com
 
 #######################
 # Sitemap configuration: https://sphinx-sitemap.readthedocs.io/
 #######################
 
 # Use RTD canonical URL to ensure duplicate pages have a specific canonical URL
 
-html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
+html_baseurl = f"https://ubuntu.com/docs/checkbox/{os.environ.get('READTHEDOCS_VERSION', 'local')}/"
+sitemap_filename = "doc-sitemap.xml"
 
 # sphinx-sitemap uses html_baseurl to generate the full URL for each page:
 
@@ -181,15 +182,17 @@
 #######################
 
 html_static_path = [".sphinx/_static"]
-# templates_path = ["_templates"]
+templates_path = [".sphinx/_templates"]
 
 # Adds custom CSS files, located under 'html_static_path'
 html_css_files = [
     "checkbox-doc.css",
 ]
 
 # Adds custom JavaScript files, located under 'html_static_path'
-# html_js_files = []
+html_js_files = [
+    "overwrite_links.js",  # support ReadTheDocs flyout when hosted at ubuntu.com/docs
+]
 
 #############
 # Redirects #

docs/index.rst

@@ -1,4 +1,4 @@
-:relatedlinks: [Diátaxis](https://diataxis.fr/)
+:relatedlinks: [Project repository](https://github.com/canonical/checkbox)
 
 .. _home: