From a5ad414142226accd2397a436a403c630a20b055 Mon Sep 17 00:00:00 2001
From: Anne Chew <anne.chew@canonical.com>
Date: Wed, 22 Apr 2026 11:50:03 +0800
Subject: [PATCH] docs: import ulwazi theme

Signed-off-by: Anne Chew <anne.chew@canonical.com>
---
 docs/_templates/footer.html | 128 ++++++++++-----------------------
 docs/_templates/header.html | 137 +++++++++++++++++++++---------------
 docs/conf.py                |  67 ++++++++++++++----
 docs/index.rst              |   1 +
 docs/requirements.txt       |  16 +++--
 5 files changed, 186 insertions(+), 163 deletions(-)

diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html
index f4ccfe04..12ccc4dd 100644
--- a/docs/_templates/footer.html
+++ b/docs/_templates/footer.html
@@ -1,92 +1,42 @@
-<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 }}">Copyright</a> &#169; {{ copyright }}
-        {%- endtrans %}
-      {%- else %}
-        {% trans copyright=copyright|e -%}
-          Copyright &#169; {{ copyright }}
-        {%- endtrans %}
-      {%- endif %}
+<footer class="l-docs__footer p-strip is-dark">
+  <div class="l-docs__subgrid">
+    <div class="l-docs__sidebar u-fixed-width">
+      <p>&copy; {{ copyright }} {{ author }}</p>
     </div>
-    {%- 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 class="l-docs__main">
+      <nav class="row" aria-label="Footer">
+        <ul class="p-list">
+          {%- if footer and footer.product -%}
+          <li class="p-list__item">
+            {%- if product_page %}
+            <a href="{{ product_page }}">{{ project }} {{ version }}</a>
+            {%- else -%}
+            {{ project }} {{ version }}
+            {%- endif -%}
+          </li>
+          {%- endif -%}
+          {%- if footer and footer.license and license and license.name -%}
+          <li class="p-list__item">
+            {%- if license.url -%}
+            This page is licensed under <a href="{{ license.url }}">{{ license.name }}</a>
+            {%- else -%}
+            This page is licensed under {{ license.name }}
+            {%- endif -%}
+          </li>
+          {%- endif -%}
+          {%- if footer and footer.entries -%}
+            {%- for item in footer.entries -%}
+            <li class="p-list__item">
+              {{ item }}
+            </li>
+            {%- endfor -%}
+          {%- endif -%}
+        </ul>
+        <span class="u-off-screen">
+          <!-- Non-functional -->
+          <a href="#">Go to the top of the page</a>
+        </span>
+      </nav>
     </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>
\ No newline at end of file
+</footer>
\ No newline at end of file
diff --git a/docs/_templates/header.html b/docs/_templates/header.html
index 9ee3c77d..aebaf629 100644
--- a/docs/_templates/header.html
+++ b/docs/_templates/header.html
@@ -1,72 +1,95 @@
-<header id="header" class="p-navigation">
+{% macro nav_logo() %}
+<div class="p-navigation__tagged-logo">
+  <a class="p-navigation__link" href="{{ logo_link_URL }}">
+    <div class="p-navigation__logo-tag">
+      <img class="p-navigation__logo-icon" src="{{ logo_img_URL }}" alt="">
+    </div>
+    <span class="p-navigation__logo-title">{{ logo_title }}</span>
+  </a>
+</div>
+<a href="#navigation" class="p-navigation__toggle--open" title="menu">Menu</a>
+<a href="#navigation-closed" class="p-navigation__toggle--close" title="close menu">Close menu</a>
+{% endmacro %}
 
-  <!-- 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>
+{% macro nav_items() %}
+<ul class="p-navigation__items">
+  <li class="p-navigation__item">
+    <a class="p-navigation__link" href="https://{{ product_page }}">{{ project }}</a>
+  </li>
 
-  <div class="p-navigation__nav" role="menubar">
+  {% if link1_name and link1_URL %}
+  <li class="p-navigation__item">
+    <a class="p-navigation__link" href="{{ link1_URL }}">{{ link1_name }}</a>
+  </li>
+  {% endif %}
 
-    <ul class="p-navigation__links" role="menu">
+  {% if link2_name and link2_URL %}
+  <li class="p-navigation__item">
+    <a class="p-navigation__link" href="{{ link2_URL }}">{{ link2_name }}</a>
+  </li>
+  {% endif %}
 
+  <li class="p-navigation__item--dropdown-toggle" id="link-2">
+    <a href="#link-2-menu" aria-controls="link-2-menu" class="p-navigation__link">Resources</a>
+    <ul class="p-navigation__dropdown" id="link-2-menu" aria-hidden="true">
+      {% if discourse %}
       <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>
+        <a href="{{ discourse }}" class="p-navigation__dropdown-item">Discourse</a>
       </li>
+      {% endif %}
 
-      <li class="nav-ubuntu-com">
-        <a href="https://{{ product_page }}" class="p-navigation__link">{{ product_page }}</a>
+      {% if mattermost %}
+      <li>
+        <a href="{{ mattermost }}" class="p-navigation__dropdown-item">Mattermost</a>
       </li>
+      {% endif %}
 
+      {% if matrix %}
       <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>
+        <a href="{{ matrix }}" class="p-navigation__dropdown-item">Matrix</a>
       </li>
+      {% endif %}
 
+      {% if github_url %}
+      <li>
+        <a href="{{ github_url }}" class="p-navigation__dropdown-item">GitHub</a>
+      </li>
+      {% endif %}
     </ul>
+  </li>
+</ul>
+{% endmacro %}
+<header id="navigation" class="p-navigation is-dark">
+  <!-- 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],
+        j = d.createElement(s),
+        dl = l != 'dataLayer' ? '&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>
+  <a href="#content" class="p-link--skip">Jump to main content</a>
+  <div class="l-docs__subgrid">
+    <div class="l-docs__sidebar">
+      <div class="p-navigation__banner">
+        {{ nav_logo() }}
+      </div>
+    </div>
+    <div class="l-docs__main">
+      <div class="p-navigation__row u-fixed-width">
+        <nav class="p-navigation__nav" aria-label="Main">
+          {{ nav_items() }}
+        </nav>
+      </div>
+    </div>
   </div>
 </header>
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
index b0aad1f5..a6ea504b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -75,6 +75,13 @@
 
 # html_favicon = '.sphinx/_static/favicon.png'
 
+# Repository and source defaults used by fallback view/edit links.
+github_repo = "https://github.com/canonical/sphinx-docs-starter-pack"
+default_source_extension = ".rst"
+
+# Product page URL; can be different from docs URL.
+product_page = "https://canonical-starter-pack.readthedocs-hosted.com"
+
 
 # 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
@@ -88,7 +95,10 @@
     # TODO: If there's no such website,
     #       remove the {{ product_page }} link from the page header template
     #       (usually .sphinx/_templates/header.html; also, see README.rst).
-    "product_page": "documentation.ubuntu.com",
+    "product_page": product_page,
+    # Inherit project name
+    "project": project,
+
     # 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.
@@ -114,7 +124,7 @@
     #
     # NOTE: If set, links for viewing the documentation source files
     #       and creating GitHub issues are added at the bottom of each page.
-    "github_url": "https://github.com/canonical/sphinx-docs-starter-pack",
+    "github_url": github_repo,
     # Docs branch in the repo; used in links for viewing the source files
     #
     # TODO: To customise the branch, uncomment and update as needed.
@@ -131,8 +141,18 @@
     # TODO: To enable listing contributors on individual pages, set to True
     "display_contributors": False,
 
-    # Required for feedback button    
-    'github_issues': 'enabled',
+    # Required for feedback button
+    "feedback": True,
+    "github_issues": "enabled",
+    "default_source_extension": default_source_extension,
+    "default_edit_url": github_repo + "/edit/main/docs/index" + default_source_extension,
+    "default_view_url": github_repo + "/blob/main/docs/index" + default_source_extension,
+
+    # Horizontal Nav Menu
+    "company": "Canonical",
+    "logo_link_URL": "https://canonical.com",
+    "logo_img_URL": "https://assets.ubuntu.com/v1/82818827-CoF_white.svg",
+    "logo_title": "Canonical",
 
     # Inherit the author value
     "author": author,
@@ -151,7 +171,16 @@
 
     "license": {
         "name": "CC-BY-SA-3.0",
-        "url": "https://github.com/canonical/sphinx-docs-starter-pack/blob/main/LICENSE",
+        "url": github_repo + "/blob/main/LICENSE",
+    },
+
+    # Footer entries shown in the global footer area.
+    "footer": {
+        "product": False,
+        "license": True,
+        "entries": [
+            '<a class="js-revoke-cookie-manager" href="#tracker-settings">Manage your tracker settings</a>',
+        ],
     },
 }
 
@@ -211,6 +240,8 @@
 # Template and asset locations #
 ################################
 
+html_theme = "ulwazi"
+
 # html_static_path = ["_static"]
 # templates_path = ["_templates"]
 
@@ -273,10 +304,12 @@
 # Custom Sphinx extensions; see
 # https://www.sphinx-doc.org/en/master/usage/extensions/index.html
 
-# NOTE: The canonical_sphinx extension is required for the starter pack.
+# NOTE: Ulwazi and canonical_sphinx_config replace canonical_sphinx defaults.
 
 extensions = [
-    "canonical_sphinx",
+    "ulwazi",
+    "canonical_sphinx_config",
+    "myst_parser",
     "notfound.extension",
     "sphinx_design",
     "sphinx_rerediraffe",
@@ -296,6 +329,7 @@
     "sphinx_last_updated_by_git",
     "sphinx.ext.intersphinx",
     "sphinx_sitemap",
+    "sphinx_modern_pdf_style",
 ]
 
 # Excludes files or directories from processing
@@ -307,16 +341,20 @@
 
 # Adds custom CSS files, located under '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 under '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",
+]
+
+# Syntax highlighting settings
+highlight_language = "none"
+pygments_style = "autumn"
 
 
 # Specifies a reST snippet to be appended to each .rst file
@@ -377,3 +415,6 @@
 intersphinx_mapping = {
     'sphinxcontrib-mermaid': ('https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest', None)
 }
+
+# PDF output configuration
+set_modern_pdf_config = True
diff --git a/docs/index.rst b/docs/index.rst
index 98c5785f..3ca946c0 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -50,6 +50,7 @@ The Canonical Sphinx starter pack is an open source project that warmly welcomes
     :hidden:
     :maxdepth: 2
 
+    Home <self>
     Set up a new project <set-up-a-new-project>
     How-to guides <how-to/index>
     Reference <reference/index>
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 6016a35a..930a3eaa 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,9 +1,16 @@
-# Canonical theme (still needed for Furo theme and custom templates)
-canonical-sphinx~=0.6
+# Core Sphinx dependencies
+sphinx
+build
+sphinx-autobuild
+
+# Ulwazi theme and config integration
+canonical-sphinx-config @ git+https://github.com/canonical/canonical-sphinx-config.git@main
+ulwazi
+sphinx-basic-ng
+beautifulsoup4
 
-# Extensions previously auto-loaded by canonical-sphinx
+# Extensions required by the theme and this docs set
 myst-parser~=4.0    # v5.0.0 causes version conflicts
-sphinx-autobuild
 sphinx-design
 sphinx-notfound-page
 sphinx-reredirects
@@ -27,6 +34,7 @@ packaging
 sphinxcontrib-svg2pdfconverter[CairoSVG]
 sphinx-last-updated-by-git
 sphinx-sitemap
+sphinx_modern_pdf_style
 
 # Vale dependencies
 rst2html