From d9025e55d3b80eb492dc4ec130a197de82df1bac Mon Sep 17 00:00:00 2001 From: MengT Date: Mon, 13 Jul 2026 17:01:03 +0800 Subject: [PATCH 1/6] feat(docs): enable Google Analytics cookie banner in html templates --- docs/.sphinx/_templates/footer.html | 103 ++++++++++++++++++++++++++++ docs/.sphinx/_templates/header.html | 72 +++++++++++++++++++ docs/conf.py | 2 +- 3 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 docs/.sphinx/_templates/footer.html create mode 100644 docs/.sphinx/_templates/header.html diff --git a/docs/.sphinx/_templates/footer.html b/docs/.sphinx/_templates/footer.html new file mode 100644 index 0000000000..e1d108891a --- /dev/null +++ b/docs/.sphinx/_templates/footer.html @@ -0,0 +1,103 @@ +
+ {# 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") -%} + +
+
+ {{ _("Next") }} +
+
{{ next.title }}
+
+ + + {%- endif %} + {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%} + + +
+
+ {{ _("Previous") }} +
+ {% if prev.link == pathto(root_doc) %} +
{{ _("Home") }}
+ {% else %} +
{{ prev.title }}
+ {% endif %} +
+ + {%- endif %} + {%- endif %} +
+
+
+ {%- if show_copyright %} +
+ {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e -%} + © {{ copyright }} {{ author }} + {%- endtrans %} + {%- else %} + {% trans copyright=copyright|e -%} + © {{ copyright }} {{ author }} + {%- endtrans %} + {%- endif %} +
+ {%- endif %} + {%- if license and license.name -%} + {%- if license.url -%} +
+ This page is licensed under {{ license.name }} +
+ {%- else -%} +
+ This page is licensed under {{ license.name }} +
+ {%- endif -%} + {%- endif -%} + + {# mod: removed "Made with" #} + + {%- if last_updated -%} +
+ {% trans last_updated=last_updated|e -%} + Last updated on {{ last_updated }} + {%- endtrans -%} +
+ {%- endif %} + + {%- if show_source and has_source and sourcename %} +
+ Show source +
+ {%- endif %} +
+
+ {% 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 %} + Thanks to the {{ contributors |length }} contributors! + {% else %} + Thanks to our contributor! + {% endif %} +
+ + {% endif %} + {% endif %} +
+
Manage your tracker settings
+
\ No newline at end of file diff --git a/docs/.sphinx/_templates/header.html b/docs/.sphinx/_templates/header.html new file mode 100644 index 0000000000..9ee3c77d80 --- /dev/null +++ b/docs/.sphinx/_templates/header.html @@ -0,0 +1,72 @@ + \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 7a9c648fa2..1c9c3a6cad 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -181,7 +181,7 @@ ####################### html_static_path = [".sphinx/_static"] -# templates_path = ["_templates"] +templates_path = [".sphinx/_templates"] # Adds custom CSS files, located under 'html_static_path' html_css_files = [ From 179ff411583124d59aedd1030413164b81b16e56 Mon Sep 17 00:00:00 2001 From: MengT Date: Mon, 13 Jul 2026 17:05:48 +0800 Subject: [PATCH 2/6] feat(docs): add js to overwrite links in RTD fly-out --- docs/.sphinx/_static/overwrite_links.js | 52 +++++++++++++++++++++++++ docs/conf.py | 4 +- 2 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 docs/.sphinx/_static/overwrite_links.js diff --git a/docs/.sphinx/_static/overwrite_links.js b/docs/.sphinx/_static/overwrite_links.js new file mode 100644 index 0000000000..d924f6b6c1 --- /dev/null +++ b/docs/.sphinx/_static/overwrite_links.js @@ -0,0 +1,52 @@ +// Replaces rtd-address with new-address in links + +const rtd_address = 'canonical-checkbox-documentation.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); +} diff --git a/docs/conf.py b/docs/conf.py index 1c9c3a6cad..a63dfc306d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -189,7 +189,9 @@ ] # 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 # From 2e139a5b21d00423d4ff6418007a1a624f2f9049 Mon Sep 17 00:00:00 2001 From: MengT Date: Mon, 13 Jul 2026 17:12:40 +0800 Subject: [PATCH 3/6] chore(docs): update URL and sitemap config --- docs/conf.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a63dfc306d..3f73a89a19 100644 --- a/docs/conf.py +++ b/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 @@ -158,7 +158,7 @@ # 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/ @@ -166,7 +166,8 @@ # 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: From 7f950152ae88a94b51594df991cfd3953dd6800f Mon Sep 17 00:00:00 2001 From: MengT Date: Wed, 22 Jul 2026 00:17:11 +0800 Subject: [PATCH 4/6] feat(docs): switch to existing RTD project address --- docs/.sphinx/_static/overwrite_links.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/.sphinx/_static/overwrite_links.js b/docs/.sphinx/_static/overwrite_links.js index d924f6b6c1..f2cf7cff18 100644 --- a/docs/.sphinx/_static/overwrite_links.js +++ b/docs/.sphinx/_static/overwrite_links.js @@ -1,6 +1,6 @@ // Replaces rtd-address with new-address in links -const rtd_address = 'canonical-checkbox-documentation.readthedocs-hosted.com'; +const rtd_address = 'canonical-checkbox.readthedocs-hosted.com'; const new_address = 'ubuntu.com/docs/checkbox'; function escapeRegExp(value) { From 298c43311a92eb95869a0a24111ca12a8126e3ae Mon Sep 17 00:00:00 2001 From: MengT Date: Wed, 22 Jul 2026 00:19:33 +0800 Subject: [PATCH 5/6] chore(docs): update edit button and related links --- docs/conf.py | 6 +++--- docs/index.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3f73a89a19..f1fb84ddde 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -149,9 +149,9 @@ # - 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 # diff --git a/docs/index.rst b/docs/index.rst index 02526481ed..7beba25869 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -:relatedlinks: [Diátaxis](https://diataxis.fr/) +:relatedlinks: [Project repository](https://github.com/canonical/checkbox) .. _home: From 14117d803c700dd715444d8ce34a6e53f47ceda5 Mon Sep 17 00:00:00 2001 From: MengT Date: Wed, 22 Jul 2026 13:09:37 +0800 Subject: [PATCH 6/6] reformat --- docs/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index f1fb84ddde..751ec0d4c6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -150,7 +150,7 @@ # - https://git.launchpad.net/example # html_theme_options = { - 'source_edit_link': 'https://github.com/canonical/checkbox', + "source_edit_link": "https://github.com/canonical/checkbox", } # Project slug; see https://meta.discourse.org/t/what-is-category-slug/87897 @@ -158,7 +158,7 @@ # TODO: If your documentation is hosted on https://docs.ubuntu.com/, # uncomment and update as needed. -slug = 'docs/checkbox' # required when hosted on ubuntu.com +slug = "docs/checkbox" # required when hosted on ubuntu.com ####################### # Sitemap configuration: https://sphinx-sitemap.readthedocs.io/ @@ -191,7 +191,7 @@ # Adds custom JavaScript files, located under 'html_static_path' html_js_files = [ - "overwrite_links.js", # support ReadTheDocs flyout when hosted at ubuntu.com/docs + "overwrite_links.js", # support ReadTheDocs flyout when hosted at ubuntu.com/docs ] #############