Sphinx Stack 3.0¶
16 October 2026
These release notes cover new features and changes in the Sphinx Stack. For a more granular list of changes, check out the full commit log.
Bring these changes into your docs:
What’s new¶
New theme¶
Sphinx Stack 3.0 is the first to ship with default support for Ulwazi, our new Sphinx theme based on the Vanilla web framework. Its 1.0 release is the culmination of a long effort from several authors, and it represents a leap forward in the look and feel of Canonical documentation.
To set up and configure Ulwazi, follow the steps in Configure the Ulwazi theme as part of your next update. If you run into any bugs or issues during adoption, please report them on GitHub.
New local documentation workflow¶
Sphinx Stack 3.0 introduces a new workflow for running the spelling, inclusive language, and link checks. Instead of calling the older remote workflow, which points right back to the project’s Makefile, the new workflow is self-contained. This change brings more secure, performant, and easily customizable documentation checks to your project’s CI pipeline.
To bring in these improvements, copy the new automatic-doc-checks.yaml
file into your project’s .github/workflows/ directory during your next update.
New CLI¶
The Sphinx Stack isn’t a tool, but it’s not only a collection of files, either. Every
time you use it, you enter commands in the terminal, using special words like html
and vale. It in effect contains a CLI experience like many of the tools Canonical
ships, only without a standalone binary package. The ergonomics of the Sphinx Stack –
how it fits, feels, and responds to your input – is important.
We’re in the process of remaking the CLI. Our intent is to bring it into compliance with the design and user experience standards at Canonical, and put it at par with other best-in-class Canonical tools. Reworking all 14 commands using a new task runner takes much iteration and testing, so we’ve slated it for the Sphinx Stack 4.0 release. If you’d like to follow development, you can find the latest working version in the cli-redesign branch.
Breaking changes¶
Required job names¶
On GitHub, required jobs in CI are selected based on their name. So, if you require pull requests to pass the spelling, inclusive language, and link checks in your project, you must update your repository settings with the new job names.
For example, if your repository lists “documentation-checks / Spell check” as a required check, replace it with “Documentation / Spelling check”.
Removed none role¶
The Sphinx Stack now defaults to version 1.0 of the sphinx-roles extension, which removed
the none role.
Replace any uses of the none role with comments:
- :none:`This text isn't rendered.`
+ .. This text isn't rendered.
Removed sphinx-tabs extension¶
The sphinx-tabs extension is no longer included by default.
If your documentation contains tabs and tab directives, replace them with the
tab-set and tab-item directives from the sphinx-design extension:
- .. tabs::
-
- .. tab:: Item 1
-
- This is the first item.
-
- .. tab:: Item 2
-
- This is the second item.
+ .. tab-set::
+
+ .. tab-item:: Item 1
+
+ This is the first item.
+
+ .. tab-item:: Item 2
+
+ This is the second item.
Removed sphinx-contributor-listing extension¶
The sphinx-contributor-listing extension is no longer included by default.
This extension isn’t supported by Ulwazi, as it no longer aligns with our best practices for page headers and footers. If your project still includes references to this extension in its footer, remove them from the footer template when you update.
Removed sphinx-filtered-toctree extension¶
The sphinx-filtered-toctree extension is no longer included by default. This extension was part of a legacy feature and is no longer needed.
If your conf.py file assigns a value to toc_filter_exclude, remove the line:
- toc_filter_exclude = ["foo", "bar"]
Then, replace any filtered-toctree directives with the toctree directive:
- .. filtered-toctree::
-
- page-a
- :foo:page-b
+ .. toctree::
+
+ page-a
If you find a page prefixed with one of the strings previously listed with
toc_filter_exclude, evaluate its usefulness. If it should be rendered, remove the
prefix. If not, delete the entry and its respective file.
Removed sphinx-last-updated-by-git extension¶
The sphinx-last-updated-by-git extension is no longer included by default. Its inclusion
in the docs/requirements.txt file was redundant, as it’s already set up by the
sphinx-sitemap extension, which all Canonical documentation projects should use.
Ensure that you have the sphinx-sitemap extension installed and configured. For guidance, refer to Sitemaps.
Removed sphinx-ubuntu-images extension¶
The sphinx-ubuntu-images extension is no longer included by default. This extension isn’t commonly used and therefore isn’t suited for the inclusion in the Sphinx Stack.
If your documentation does use the ubuntu-images directive, be sure to add it back
to your requirements.txt and conf.py files after you update.
Removed sphinx-reredirects extension¶
The sphinx-reredirects extension is no longer included by default. Redirects, both internal and external, should be handled with the sphinx-rerediraffe extension.
For guidance on redirecting pages with the sphinx-rerediraffe extension, follow the steps in Redirect pages.
Deprecated features¶
The following features are deprecated. We plan to remove them in the 4.0 release.
Python 3.10¶
Python 3.10 reached end of life on 1 October 2026 and will not be supported in Sphinx Stack 4.0 and higher.
Several Sphinx Stack dependencies, including Sphinx itself, have already dropped Python 3.10 support in recent releases. To ensure that the Sphinx Stack can continue to incorporate and deliver upstream improvements, its 4.0 release will follow suit. This change will break compatibility with stock Ubuntu 22.04 LTS systems, which shipped with Python 3.10.4. Keep this in mind when setting up documentation environments and CI runners moving forward.
Callable workflows¶
The following Sphinx Stack workflows will no longer be callable in Sphinx Stack 4.0 and higher:
sphinx-python-dependency-build-check.yamlmarkdown-style-checks.yamlcheck-removed-urls.yaml
These workflows are meant to be duplicated in downstream projects, and the inclusion of
the workflow_call trigger has been misleading for many projects.
If you need to call these workflows across a wide spread of projects and don’t want to maintain multiple copies, it’s recommended that you maintain your own callable source workflows. This will give you more granular control over their behavior and will make you more resilient to Sphinx Stack changes.
requirements.txt file¶
The docs/requirements.txt file is being replaced with a docs/pyproject.toml file
in Sphinx Stack 4.0.
A pyproject.toml file will allow more flexibility and reproducibility in documentation
builds and is preferred in modern Python. If your project has additional tooling
referencing the current requirements.txt file path, such as custom Make targets or CI
workflows, then you’ll need to update the path when you update to Sphinx Stack 4.0.
Dependency changes¶
Package |
From |
To |
|---|---|---|
ulwazi |
~=1.0 |
|
packaging |
~=26.1 |
~=26.3 |
sphinx-autobuild |
==2024.10.03 |
|
sphinx-llm |
~=0.4 |
~=1.1 |
sphinx-rerediraffe |
>0.0.3, <1.0.0 |
~=0.1 |
sphinx-roles |
~=0.1 |
~=1.0 |
sphinx-terminal |
~=1.0 |
~=1.1 |
Some Sphinx Stack dependencies can’t be updated until we drop Python 3.10 in the 4.0 release. These dependencies are being tracked in https://github.com/canonical/sphinx-stack/issues/645. If you encounter a similar breakage with the current set of constraints, please describe it in the issue thread.
Bug fixes¶
The following bugs were fixed for the 3.0 release:
Contributors¶
We’d like to express a big thank you to everyone who contributed to this release:
asanvaq,
a-velasco,
bepri,
bjdean-canonical,
dwilding,
edibotopic,
elijahgreenstein,
erinecon,
geoffreynyaga,
izmalk,
jahn-junior,
JordanMG13,
medubelko,
mhsun-se,
nhennigan,
odadacharles,
rajannpatel,
rkratky,
SecondSkoll,
shaloo, and
zayatamal