Skip to content

Releases: canonical/sphinx-stack

2.0

01 May 03:50
@jahn-junior jahn-junior
2.0
This tag was signed with the committer’s verified signature.
jahn-junior JJ Coldiron
GPG key ID: 899C616FBAB62C0A
Verified
Learn about vigilant mode.
c549bf4
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
2.0 Latest
Latest

Canonical’s Sphinx Starter Pack 2.0

30 April 2026

These release notes cover new features and changes in the project formerly known as Canonical's Sphinx Starter Pack. For a more granular list of changes, check out the full commit log.

Bring these changes into your docs:

What’s new

Rename to Sphinx Stack

This project was named when the documentation team at Canonical started assembling a standard documentation toolkit. The word starter felt appropriate, as products needed their documentation bootstrapped, and we had yet to release a standard. More than two years later, this is no longer the case. This project has been deployed in hundreds of Canonical products. It now represents a complete standard for Canonical documentation sets, not just those starting out. So, we decided that it's time for a new name.

With the release of version 2.0, we’re renaming the project Sphinx Stack. The repository is now located at https://github.com/canonical/sphinx-stack.

Separate documentation repository

To simplify the process of setting up and maintaining the Sphinx Stack, we separated its documentation into a new Sphinx Stack documentation repository.

Now, when you create a new project with the Sphinx Stack, you no longer need to remove its documentation. New projects are also no longer initialized with any configuration specific to the Sphinx Stack docs. Now, there’s less ambiguity as to whether you need to incorporate new values into your configuration file.

sphinx-llm support

This version introduces default support for the sphinx-llm extension. It surfaces documents in accordance with the emerging llms.txt standard.

You can think of the llms.txt as an extra sitemap for LLMs and systems using the Model Context Protocol. In your documentation builds, you’ll now see an llms.txt file, an llms-full.txt file, and Markdown copies of your pages. The content of these files is copied straight from your existing docs – it doesn't transform or summarize the text.

Dependency constraints

In the past, we’ve had upstream packages break documentation builds without warning. To reduce this, we constrained the project’s dependencies to their current major version.

Before every future major release, we’ll test the newest versions and adjust the constraints appropriately.

Copyright statement

We aligned the copyright statement in the footer with legal standards. To incorporate this change in your documentation, add the license information to html_context in your conf.py file:

html_context = {
    "license": {
        "name": "CC-BY-SA-3.0",
        "url": "https://github.com/canonical/sphinx-docs-starter-pack/blob/main/LICENSE",
    },
}

For license.name, use the standard shorthand identifier from SPDX.

For license.url, link to the LICENSE statement, typically found on the product’s home page or in its GitHub repository.

Ulwazi testing

We invite you to test Ulwazi, our new documentation theme in early access.

It represents a leap forward in the user experience, and we'd like your feedback. If you run into any bugs or issues, please report them on GitHub.

Breaking changes

Renamed the .sphinx/ directory

The .sphinx/ directory, which contains config files and utility scripts, has been renamed to _dev to better reflect its purpose.

Once you’ve updated, remember to remove the .sphinx directory from your project. If your project has custom code that references this directory, you’ll also need to update these references.

Removed the reuse/ directory

To reduce complexity and improve source readability, we’ve removed the reuse/ directory.

By default, this directory contained project-wide link URLs and substitutions. Links should now be included with the inline syntax or, if used more than three times in a file, included at the end of the file. Substitutions will need to use reST or MyST syntax and should be placed at the top of the file. The syntax for these changes is described in External links and Substitution.

Deprecated features

The following features are deprecated. We plan to remove them in the 3.0 release.

none role

The none role is deprecated in 2.0.

To prepare for this change, replace any uses of the role with comments:

- :none:`This text isn't rendered.`
+ .. This text isn't rendered.

sphinx-tabs extension

The sphinx-tabs extension is deprecated in 2.0.

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.

sphinx-contributor-listing extension

The sphinx-contributor-listing extension is deprecated in 2.0. To simplify the header and footer design, we’re ending support for per-page contributor lists in the next major release.

sphinx-filtered-toctree extension

The sphinx-filtered-toctree extension is deprecated in 2.0. 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.

sphinx-last-updated-by-git extension

The sphinx-last-updated-by-git extension is deprecated in 2.0. Its inclusion in the docs/requirements.txt file is redundant, as it’s already set up by the sphinx-sitemap extension.

Ensure that you have the sphinx-sitemap extension installed and configured. For guidance, refer to Set up sitemaps.

sphinx-ubuntu-images extension

The sphinx-ubuntu-images extension is deprecated in 2.0. This extension isn’t commonly used and won’t be included by default in the next major release.

If your documentation uses the ubuntu-images directive, be sure to add it back to your requirements.txt and conf.py files after you update.

sphinx-reredirects extension

The sphinx-reredirects extension was deprecated in 1.6. Redirects, both internal and external, should now be handled with the sphinx-rerediraffe extension.

Redirect pages contains guidance on redirecting pages with the sphinx-rerediraffe extension.

Contributors

We’d like to express a big thank you to everyone who contributed to this release:

@a-velasco,
@asanvaq,
@AshleyCliff,
@izmalk,
@jahn-junior,
@keirthana,
@medubelko,
@mhsun-se
@nhennigan,
@odadacharles,
@Saviq,
@srbouffard, and
@yhontyk

Contributors

Saviq, keirthana, and 11 other contributors
Assets 2
Loading

1.6

24 Mar 19:31
@jahn-junior jahn-junior
1.6
This tag was signed with the committer’s verified signature.
jahn-junior JJ Coldiron
GPG key ID: 899C616FBAB62C0A
Verified
Learn about vigilant mode.
51e9a67
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
1.6

Canonical's Sphinx Starter Pack 1.6

23 March 2026

These release notes cover new features and changes in Canonical's Sphinx Starter Pack 1.6. You can also read the full commit log.

Bring these changes into your docs:

What's new in 1.6

New extension for redirects

If your project has a lot of redirects, they can begin to clutter your build configuration file. To remedy this, we changed the default extension for redirects to sphinx-rerediraffe, a fork of sphinxext-rediraffe that supports external redirects and cleans up destination URLs.

In your docs, you can now list redirects in a redirects.txt file and configure your project to use them with:

 - redirects = {
 -     "source-path": "destination-path"
 - }
 + rediraffe_redirects = "redirects.txt"
 + rediraffe_dir_only = True

If your project uses relative redirects, these should be rewritten relative to the root of the docs directory.

For example, if you were previously redirecting /how-to/set-up/project/ to ../set-up-project/, the redirect should now read:

 "how-to/set-up/project/" "how-to/set-up-project/"

Remote cookie banner files

Following the recent changes to the cookie banner, we evaluated how its files are distributed and maintained. In version 1.6, these files are hosted centrally so you don't need to duplicate them to enable Google Analytics for your project.

If you've already enabled Google Analytics in your project, you should make it a priority to use the centrally-hosted files, as they contain important legal changes. For guidance, refer to How to enable Google Analytics.

Virtual environment path

To make the Python virtual environment more discoverable, we moved it from docs/.sphinx/venv to docs/.venv. This also preserves the .sphinx/ directory's scope, which is to house static utility files.

Once you've replaced all occurrences of the old path, remove the old virtual environment.

Ulwazi testing guide

Our new Sphinx theme based on the Vanilla framework, Ulwazi, is now available for testing. To try it out, follow the new guide, Test the Ulwazi theme.

Starter Pack explanation

We published Starter Pack structure to explain the functionality of and relationships between the core elements of the Starter Pack.

Deprecated features

The following features are deprecated and will be removed in an upcoming version of the Starter Pack.

sphinx-reredirects

The sphinx-reredirects extension is deprecated in 1.6. Redirects, both internal and external, should now be handled with sphinx-rerediraffe.

Fixed for 1.6

  • #535 Markdown checks are incompatible with default runner version
  • #550 Makefile doesn't allow for :vale-ignore:pymarkdownlnt to exit with a status code of 1

Contributors

We would like to express a big thank you to all the people who contributed to this release:

@akcano,
@AnneCYH,
@arturo-seijas,
@jahn-junior,
@odadacharles,
@wctaylor, and
@yhontyk

Contributors

wctaylor, yhontyk, and 5 other contributors
Loading

1.5

27 Feb 02:33
@medubelko medubelko
1.5
This tag was signed with the committer’s verified signature.
medubelko Michael DuBelko
SSH Key Fingerprint: 5dB0qCjwdc/PHUFhdeOqBjbv3hySOsQR87rmg+A+jDA
Verified
Learn about vigilant mode.
c934111
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
1.5

What's Changed

New Contributors

Full Changelog: 1.4.1...1.5

Contributors

minaelee, a-velasco, and 7 other contributors
Loading

1.4.1

29 Jan 20:21
@medubelko medubelko
1.4.1
This tag was signed with the committer’s verified signature.
medubelko Michael DuBelko
SSH Key Fingerprint: 5dB0qCjwdc/PHUFhdeOqBjbv3hySOsQR87rmg+A+jDA
Verified
Learn about vigilant mode.
1b80579

Choose a tag to compare

View all tags
1.4.1

What's Changed

  • Fix the version slug so the upgrade script has the right release tag by @medubelko in #516

Full Changelog: 1.4.0...1.4.1

Contributors

medubelko
Loading

1.4.0

28 Jan 21:49
@medubelko medubelko
1.4.0
This tag was signed with the committer’s verified signature.
medubelko Michael DuBelko
SSH Key Fingerprint: 5dB0qCjwdc/PHUFhdeOqBjbv3hySOsQR87rmg+A+jDA
Verified
Learn about vigilant mode.
1318a73

Choose a tag to compare

View all tags
1.4.0

What's Changed

  • chore: remove unused metrics scripts by @tang-mm in #490
  • fix: pin myst-parser package version to 4.0 to avoid conflicts by @tang-mm in #496
  • chore: update changelog only by @minaelee in #500
  • docs: add explanation for the build and how-to for build passthroughs by @medubelko in #504
  • fix: resolve pymarkdown linting exclude path issue by @minaelee in #508
  • chore: 1.4.0 release prep by @medubelko in #511

Full Changelog: 1.3.1...1.4.0

Contributors

tang-mm, minaelee, and medubelko
Loading

1.3.1

10 Dec 11:01
@SecondSkoll SecondSkoll
1.3.1
8877f85
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
1.3.1

What's Changed

Full Changelog: 1.3.0...1.3.1

Contributors

AnneCYH and SecondSkoll
Loading

1.3.0

13 Nov 02:34
@SecondSkoll SecondSkoll
1.3.0
713ff95
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
1.3.0

What's Changed

New Contributors

Full Changelog: 1.2.0...1.3.0

Contributors

waveform80, dwilding, and 14 other contributors
Loading

1.2.0

25 Jul 01:12
@SecondSkoll SecondSkoll
1.2.0
2ad0cc1
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
1.2.0

What's Changed

New Contributors

Full Changelog: 1.1.0...1.2.0

Contributors

Saviq, simondeziel, and 12 other contributors
Loading

1.1.0

05 Jun 05:06
@SecondSkoll SecondSkoll
1.1.0
a489ae0
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
1.1.0

What's Changed

New Contributors

Full Changelog: 1.0.1...1.1.0

Contributors

waveform80, tang-mm, and 5 other contributors
Loading

1.0.1

03 Apr 00:54
@SecondSkoll SecondSkoll
1.0.1
3b56e2b
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
1.0.1

What's Changed

  • Remove .wokeignore file by @SecondSkoll in #363
  • Add sphinx-docs-guide files and establish organization by @erinecon in #360
  • fix: vale-spelling issues, adds vale documentation by @SecondSkoll in #366
  • Update links and references to style guides by @erinecon in #368
  • add Canonical acronyms and terms to spelling exceptions by @akcano in #367
  • Refactor: Improve get_vale_conf script for structure and error handling by @tang-mm in #358

New Contributors

Full Changelog: 1.0.0...1.0.1

Contributors

tang-mm, erinecon, and 2 other contributors
Loading