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)
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 @@
-
-
-
- {%- 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 -%}
-
- {%- 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 %}
-
- {%- endif %}
-
-
-
-
\ 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 49ee75fd..7b021b9c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -11,17 +11,16 @@
# 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 #
#######################
# 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,9 +28,8 @@
# 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"
+# String appended to the title of individual HTML pages
+html_title = project
# Documentation website URL
ogp_site_url = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
@@ -48,45 +46,28 @@
# 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 community links; empty values hide individual links.
"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
+ # 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,
+ # 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
"author": author,
- # Documentation license information
"license": {
# TODO: Specify your project's license.
# For the name, we recommend using the standard shorthand identifier from
@@ -97,22 +78,6 @@
},
}
-# 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 +105,6 @@
################################
# html_static_path = ["_static"]
-# templates_path = ["_templates"]
#############
# Redirects #
@@ -208,25 +172,18 @@
# Configuration extras #
########################
-# 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
# https://www.sphinx-doc.org/en/master/usage/extensions/index.html
extensions = [
- "canonical_sphinx",
- "notfound.extension",
+ "ulwazi",
+ "myst_parser",
"sphinx_design",
"sphinx_rerediraffe",
"sphinxcontrib.jquery",
"sphinxext.opengraph",
"sphinx_config_options",
"sphinx_llm.txt",
+ "sphinx_modern_pdf_style",
"sphinx_related_links",
"sphinx_roles",
"sphinx_terminal",
@@ -244,36 +201,38 @@
]
# 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 = """
# """
-# Feedback button at the top; enabled by default
-# TODO: Disable the button if your project is unsuitable for public feedback.
-# disable_feedback_button = True
+# 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 = ""
+
+# Apply modern PDF styling and configuration
+set_modern_pdf_config = 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
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 5928d4ef..87f9825c 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.7
+# Ulwazi theme
+ulwazi~=1.0
# Extensions previously auto-loaded by canonical-sphinx
myst-parser~=4.0 # v5.0.0 causes version conflicts
sphinx-autobuild==2024.10.3
sphinx-design==0.6.1
-sphinx-notfound-page~=1.1
sphinxcontrib-jquery~=4.1
sphinxext-opengraph~=0.13
sphinx-rerediraffe~=0.1
@@ -22,6 +21,7 @@ packaging~=26.3
sphinxcontrib-svg2pdfconverter[CairoSVG]~=2.1
sphinx-sitemap~=2.9
sphinx-llm~=1.1
+sphinx-modern-pdf-style~=0.1
# Vale dependencies
rst2html