<a id="release-1-4"></a>

# Canonical’s Sphinx Starter Pack 1.4

28 January 2026

These release notes cover new features and changes in Canonical’s Sphinx Starter Pack
1.4.0. The [full commit log](https://github.com/canonical/sphinx-docs-starter-pack/compare/1.3.1...1.4.0) is
available on GitHub.

## What’s new in 1.4.0

### Bridging the build

The docs build and its Make targets are hosted in the `docs` directory. If the docs
are in a larger project with its own build system, it can be difficult to maintain and
run the two separate builds.

We’ve taken some initial steps to make the docs build easier to integrate into larger
projects. With 1.4.0, the docs `Makefile` is now properly callable by a parent build
system, because the main build can ensure the `VENVDIR`, `BUILDDIR`, and `VALEDIR`
variables are set to the right locations in the project.

The new guide [Bridge project and documentation builds](https://documentation.ubuntu.com/sphinx-stack/latest/how-to/optional-customisation/bridge-project-and-docs-builds/index.html.md#bridge-project-and-docs-builds) covers in detail how to integrate the
docs build in a parent Python project.

### Build explanation

We’ve released an [explanation of the starter pack build](https://documentation.ubuntu.com/sphinx-stack/latest/explanation/build/index.html.md#build) to
share with you some of its design and inner workings.

## Removed in 1.4.0

### Metrics check

The metrics check was a set of scripts called with `make allmetrics` that collected
measures and statistics about source documents and rendered HTML files.

We’ve removed this check because it was underused and underdeveloped. There have been no
reported usages of it from any active projects at Canonical.

## Fixed bugs and issues

### 1.4.0

- [#496](https://github.com/canonical/sphinx-docs-starter-pack/pull/496) myst-parser
  causes Python dependency check to time out
- [#509](https://github.com/canonical/sphinx-docs-starter-pack/issues/509) Markdown
  linter falsely flags contents of `.sphinx` dir

### 1.4.1

- [#444](https://github.com/canonical/sphinx-docs-starter-pack/pull/516) Patch the
  `version` file so the upgrade script works

## Contributors

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

[`medubelko`](https://github.com/medubelko),
[`minaelee`](https://github.com/minaelee), and
[`tang-mm`](https://github.com/tang-mm)
