From e04447747a7488e8a210eafa1e891ad4de072cfc Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Wed, 14 Oct 2026 16:38:04 -0700 Subject: [PATCH 1/8] build(docs): incorporate Ulwazi 1.0 --- docs/_templates/footer.html | 103 ------------------------------------ docs/_templates/header.html | 72 ------------------------- docs/conf.py | 103 +++++++++++++++--------------------- docs/requirements.txt | 4 +- 4 files changed, 46 insertions(+), 236 deletions(-) delete mode 100644 docs/_templates/footer.html delete mode 100644 docs/_templates/header.html diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html deleted file mode 100644 index e1d10889..00000000 --- a/docs/_templates/footer.html +++ /dev/null @@ -1,103 +0,0 @@ -
- {# 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/_templates/header.html b/docs/_templates/header.html deleted file mode 100644 index 9ee3c77d..00000000 --- a/docs/_templates/header.html +++ /dev/null @@ -1,72 +0,0 @@ - \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 926230f4..0d71fa97 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,8 +20,8 @@ ####################### # Project name -# TODO: Update with the official name of your project or product (e.g., "Ubuntu Server") -project = "Project" +# TODO: Update with the official name of your project (e.g., "LXD documentation") +project = "Project documentation" # Author name; used in the default copyright statement in the page footer author = "Canonical Ltd." @@ -29,10 +29,6 @@ # The year in the copyright statement copyright = f"{datetime.date.today().year}" -# Sidebar documentation title -# To disable the title, set it to an empty string. -html_title = project + " documentation" - # Documentation website URL ogp_site_url = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") @@ -48,45 +44,29 @@ # TODO: To customise the favicon, uncomment and update the next line. # html_favicon = "_static/favicon.png" -# Dictionary of values to pass into the Sphinx context for all pages: -# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context +# The theme for the HTML output +html_theme = "ulwazi" + +# Dictionary of values to pass into every page's template. html_context = { - # Product page URL; can be different from product docs URL - # TODO: Change to your product website URL, dropping the 'https://' prefix (e.g., - # 'ubuntu.com/lxd'). If there's no such website, remove the {{ product_page }} - # link from the _templates/header.html file. - "product_page": "", - # Product tag image; the orange part of your logo, shown in the page header - # TODO: To add a tag image, uncomment and update as needed. - # 'product_tag': '_static/tag.png', - # Your Discourse instance URL - # TODO: Change to your Discourse instance URL or leave empty. + # Community links for the 'Resources' dropdown menu. + # TODO: Add links your project's community platforms or leave empty to hide "discourse": "", - # Your Mattermost channel URL - # TODO: Change to your Mattermost channel URL or leave empty. "mattermost": "", - # Your Matrix channel URL - # TODO: Change to your Matrix channel URL or leave empty. "matrix": "", - # Your documentation GitHub repository URL If set, links for viewing the - # documentation source files and creating GitHub issues are added at the bottom of - # each page. - # TODO: Change to your documentation GitHub repository URL or leave empty. "github_url": "", - # Docs branch in the repo; used in links for viewing the source files - "repo_default_branch": "main", - # Docs location in the repo; used in links for viewing the source files - "repo_folder": "/docs/", - # TODO: To enable or disable the Previous / Next buttons at the bottom of pages - # Valid options: none, prev, next, both - # "sequential_nav": "", - # TODO: To enable listing contributors on individual pages, set to True - "display_contributors": False, - # Required for feedback button - "github_issues": "enabled", - # Passes the top-level 'author' value to the theme - "author": author, - # Documentation license information + # TODO: Uncomment to enable the navigation buttons at the bottom of pages + # Valid options are 'none' (default), 'prev', 'next', 'both' + # "sequential_nav": "both", + # Feedback button configuration (uses `github_url` if set) + "feedback": True, + # Brand configuration for the leftmost entry in the banner + # TODO: If your project falls under a different product page, update the title, URL, + # and logo if necessary. + "logo_title": "Canonical", + "logo_link_URL": "https://canonical.com", + "logo_img_URL": "https://assets.ubuntu.com/v1/82818827-CoF_white.svg", + # License information to be rendered in the footer "license": { # TODO: Specify your project's license. # For the name, we recommend using the standard shorthand identifier from @@ -95,24 +75,21 @@ # TODO: Link directly to your project's license statement. "url": "", }, + # Pass the top-level 'author' value to the HTML base template + "author": author, + "footer": { + "license": True, + # TODO: Uncomment if your project collects Google Analytics + # "entries": [ + # '', + # "Manage your tracker settings", + # ], + }, + # Google Analytics tag + # TODO: Uncomment if your project collects Google Analytics + # "tag_id": "GTM-KNX3CJC", } -# TODO: To enable the edit button on pages, uncomment and change the link to a -# public repository on GitHub or Launchpad. Any of the following link domains -# are accepted: -# - https://github.com/example-org/example" -# - https://launchpad.net/example -# - https://git.launchpad.net/example -# -# html_theme_options = { -# 'source_edit_link': 'https://github.com/canonical/sphinx-stack', -# } - -# Project slug -# TODO: If your documentation is hosted on https://documentation.ubuntu.com/, -# uncomment and set to the RTD slug. -# slug = '' - ####################### # Sitemap configuration: https://sphinx-sitemap.readthedocs.io/ ####################### @@ -140,7 +117,6 @@ ################################ # html_static_path = ["_static"] -# templates_path = ["_templates"] ############# # Redirects # @@ -216,8 +192,8 @@ # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html extensions = [ - "canonical_sphinx", - "notfound.extension", + "ulwazi", + "myst_parser", "sphinx_design", "sphinx_rerediraffe", "sphinx_reredirects", @@ -228,6 +204,7 @@ "sphinx_contributor_listing", "sphinx_filtered_toctree", "sphinx_llm.txt", + "sphinx_modern_pdf_style", "sphinx_related_links", "sphinx_roles", "sphinx_terminal", @@ -260,6 +237,14 @@ # rst_epilog = """ # """ +# Project slug +# TODO: Set to your project slug. If your docs were hosted at +# https://canonical.com/juju/docs/ops, you'd set this to "juju/docs/ops". +slug = "" + +# Enable PDF builds +set_modern_pdf_config = True + # Feedback button at the top; enabled by default # TODO: Disable the button if your project is unsuitable for public feedback. # disable_feedback_button = True diff --git a/docs/requirements.txt b/docs/requirements.txt index c82291c4..0cb23a33 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,11 +1,10 @@ # Canonical theme (still needed for Furo theme and custom templates) -canonical-sphinx~=0.6 +ulwazi@git+https://github.com/canonical/ulwazi@work/banner-project-link # Extensions previously auto-loaded by canonical-sphinx myst-parser~=4.0 # v5.0.0 causes version conflicts sphinx-autobuild sphinx-design==0.6.1 -sphinx-notfound-page~=1.1 sphinx-reredirects==0.1.6 sphinx-tabs~=3.5 sphinxcontrib-jquery~=4.1 @@ -16,6 +15,7 @@ sphinx-rerediraffe>=0.0.3, <1.0.0 sphinx-config-options~=0.1 sphinx-contributor-listing~=0.1 sphinx-filtered-toctree~=0.1 +sphinx-modern-pdf-style~=0.1 sphinx-related-links~=0.1 sphinx-roles~=0.1 sphinx-terminal~=1.0 From 1b377549241da11decce321a5e1b53d9ec199ae3 Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Fri, 16 Oct 2026 16:22:48 +0100 Subject: [PATCH 2/8] conf.py fixes and updates --- docs/conf.py | 38 ++++++++++---------------------------- 1 file changed, 10 insertions(+), 28 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 0d71fa97..1c4dae7f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,9 +11,8 @@ # A complete list of built-in Sphinx configuration values: # https://www.sphinx-doc.org/en/master/usage/configuration.html # -# The Sphinx Stack uses the Canonical Sphinx theme to keep all documentation consistent -# and on brand: -# https://github.com/canonical/canonical-sphinx +# The Sphinx Stack uses the Ulwazi theme: +# https://github.com/canonical/ulwazi ####################### # Project information # @@ -50,15 +49,13 @@ # Dictionary of values to pass into every page's template. html_context = { # Community links for the 'Resources' dropdown menu. - # TODO: Add links your project's community platforms or leave empty to hide + # TODO: Add community links; empty values hide individual links. "discourse": "", "mattermost": "", "matrix": "", - "github_url": "", - # TODO: Uncomment to enable the navigation buttons at the bottom of pages - # Valid options are 'none' (default), 'prev', 'next', 'both' - # "sequential_nav": "both", - # Feedback button configuration (uses `github_url` if set) + "github_url": "https://github.com/canonical/sphinx-stack", + # Feedback and edit/view links require a valid `github_url`. + # TODO: Set to False to hide feedback and page controls. "feedback": True, # Brand configuration for the leftmost entry in the banner # TODO: If your project falls under a different product page, update the title, URL, @@ -79,14 +76,9 @@ "author": author, "footer": { "license": True, - # TODO: Uncomment if your project collects Google Analytics - # "entries": [ - # '', - # "Manage your tracker settings", - # ], }, - # Google Analytics tag - # TODO: Uncomment if your project collects Google Analytics + # TODO: Uncomment to override Ulwazi's Google Tag Manager container. + # Leaving this commented uses the default one. # "tag_id": "GTM-KNX3CJC", } @@ -183,10 +175,6 @@ # Custom MyST syntax extensions; see # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html -# NOTE: By default, the following MyST extensions are enabled: -# - substitution -# - deflist -# - linkify # myst_enable_extensions = set() # Custom Sphinx extensions; see @@ -242,26 +230,20 @@ # https://canonical.com/juju/docs/ops, you'd set this to "juju/docs/ops". slug = "" -# Enable PDF builds +# Apply modern PDF styling and configuration set_modern_pdf_config = True -# Feedback button at the top; enabled by default -# TODO: Disable the button if your project is unsuitable for public feedback. -# disable_feedback_button = True - # Your manpage URL # TODO: To enable manpage links, uncomment and replace {codename} with required # release, preferably an LTS release (e.g. noble). Do *not* substitute # {section} or {page}; these will be replaced by sphinx at build time # -# NOTE: If set, adding ':manpage:' to an .rst file -# adds a link to the corresponding man section at the bottom of the page. +# If set, the :manpage: role creates an inline link to the manual page. # manpages_url = 'https://manpages.ubuntu.com/manpages/{codename}/en/' + \ # 'man{section}/{page}.{section}.html' # Specifies a reST snippet to be prepended to each .rst file # This defines a :center: role that centers table cell content. -# This defines a :h2: role that styles content for use with PDF generation. rst_prolog = """ .. role:: center :class: align-center From fa84abc251d67aeb0165b51f172bb25f0d2fcf13 Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Fri, 16 Oct 2026 16:39:11 +0100 Subject: [PATCH 3/8] Set Ulwazi version to be 1.0.x latest --- docs/requirements.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 0cb23a33..8e3c32c6 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ -# Canonical theme (still needed for Furo theme and custom templates) -ulwazi@git+https://github.com/canonical/ulwazi@work/banner-project-link +# Ulwazi theme; allow updates within the 1.0.x series +ulwazi~=1.0.1 # Extensions previously auto-loaded by canonical-sphinx myst-parser~=4.0 # v5.0.0 causes version conflicts From d2b3200460b29f250517984d82865d97bd360c56 Mon Sep 17 00:00:00 2001 From: JJ Coldiron Date: Fri, 16 Oct 2026 14:21:31 -0700 Subject: [PATCH 4/8] fix: reassign html_title --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 1c4dae7f..092a2c4a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,6 +28,9 @@ # The year in the copyright statement copyright = f"{datetime.date.today().year}" +# String appended to the title of individual HTML pages +html_title = project + # Documentation website URL ogp_site_url = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") From fbfa1424ca2ea01ad0c65f55d9603832082a2201 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Fri, 16 Oct 2026 16:22:25 -0700 Subject: [PATCH 5/8] chore: tweak for Ulwazi 1.0.2 --- docs/conf.py | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 092a2c4a..6a0402b1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -56,7 +56,7 @@ "discourse": "", "mattermost": "", "matrix": "", - "github_url": "https://github.com/canonical/sphinx-stack", + "github_url": "", # Feedback and edit/view links require a valid `github_url`. # TODO: Set to False to hide feedback and page controls. "feedback": True, @@ -67,6 +67,7 @@ "logo_link_URL": "https://canonical.com", "logo_img_URL": "https://assets.ubuntu.com/v1/82818827-CoF_white.svg", # License information to be rendered in the footer + "author": author, "license": { # TODO: Specify your project's license. # For the name, we recommend using the standard shorthand identifier from @@ -76,13 +77,6 @@ "url": "", }, # Pass the top-level 'author' value to the HTML base template - "author": author, - "footer": { - "license": True, - }, - # TODO: Uncomment to override Ulwazi's Google Tag Manager container. - # Leaving this commented uses the default one. - # "tag_id": "GTM-KNX3CJC", } ####################### @@ -215,14 +209,14 @@ ] # Adds custom CSS files, located remotely or in 'html_static_path'. -# html_css_files = [ -# "https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css", -# ] +html_css_files = [ + "https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css", +] # Adds custom JavaScript files, located remotely or in 'html_static_path'. -# html_js_files = [ -# "https://assets.ubuntu.com/v1/287a5e8f-bundle.js", -# ] +html_js_files = [ + "https://assets.ubuntu.com/v1/287a5e8f-bundle.js", +] # Appends extra markup to the end of every document written in reST # rst_epilog = """ From b9fc4c7582e28eb0606d7dda275fe8156f212185 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Fri, 16 Oct 2026 16:23:50 -0700 Subject: [PATCH 6/8] fix: drop comment --- docs/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 6a0402b1..42268018 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -76,7 +76,6 @@ # TODO: Link directly to your project's license statement. "url": "", }, - # Pass the top-level 'author' value to the HTML base template } ####################### From 6f4370145d3b91c4b8182865c2674e11ab97ca46 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Fri, 16 Oct 2026 18:34:38 -0700 Subject: [PATCH 7/8] chore: incorporate remaining Ulwazi 1.0.2 tweaks --- docs/conf.py | 4 ---- docs/requirements.txt | 4 ++-- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 42268018..97ffc885 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -169,10 +169,6 @@ # Configuration extras # ######################## -# Custom MyST syntax extensions; see -# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html -# myst_enable_extensions = set() - # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html extensions = [ diff --git a/docs/requirements.txt b/docs/requirements.txt index 8e3c32c6..dc923e6f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ -# Ulwazi theme; allow updates within the 1.0.x series -ulwazi~=1.0.1 +# Ulwazi theme +ulwazi~=1.0 # Extensions previously auto-loaded by canonical-sphinx myst-parser~=4.0 # v5.0.0 causes version conflicts From 03e5001939de7b3a54d9f6fafa68530750c6f0e6 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Fri, 16 Oct 2026 18:51:05 -0700 Subject: [PATCH 8/8] docs: finalize changelog for 3.0 release --- CHANGELOG.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a3d93b90..b54e1c9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # sphinx-stack changelog -## Upcoming +## 3.0 * Make removed URL check redirect-aware and add support for reusable workflow contexts * Exclude utility directories from builds and checks @@ -11,12 +11,15 @@ * Update and pin CI actions * Remove extensions deprecated in 2.0 * Replace remote documentation checks in CI +* Add default support for the Ulwazi theme ### Changed -* `docs/conf.py` [#610](https://github.com/canonical/sphinx-stack/pull/610), [#634](https://github.com/canonical/sphinx-stack/pull/634), [#646](https://github.com/canonical/sphinx-stack/pull/646) +* `docs/conf.py` [#610](https://github.com/canonical/sphinx-stack/pull/610), [#634](https://github.com/canonical/sphinx-stack/pull/634), [#646](https://github.com/canonical/sphinx-stack/pull/646), [#650](https://github.com/canonical/sphinx-stack/pull/650) * `docs/Makefile` [#605](https://github.com/canonical/sphinx-stack/pull/605), [#610](https://github.com/canonical/sphinx-stack/pull/610), [#627](https://github.com/canonical/sphinx-stack/pull/627), [#628](https://github.com/canonical/sphinx-stack/pull/628) -* `docs/requirements.txt` [#634](https://github.com/canonical/sphinx-stack/pull/634), [#646](https://github.com/canonical/sphinx-stack/pull/646) +* `docs/requirements.txt` [#634](https://github.com/canonical/sphinx-stack/pull/634), [#646](https://github.com/canonical/sphinx-stack/pull/646), [#650](https://github.com/canonical/sphinx-stack/pull/650) +* `docs/_templates/header.html` [#650](https://github.com/canonical/sphinx-stack/pull/650) +* `docs/_templates/footer.html` [#650](https://github.com/canonical/sphinx-stack/pull/650) * `README.md` [#603](https://github.com/canonical/sphinx-stack/pull/603) * `.github/workflows/automatic-doc-checks.yml` [#642](https://github.com/canonical/sphinx-stack/pull/642) * `.github/workflows/cla-check.yml` [#606](https://github.com/canonical/sphinx-stack/pull/606), [#648](https://github.com/canonical/sphinx-stack/pull/648)