The Sphinx extension¶
moneta_sphinx renders the changelog into a Sphinx site. It runs
moneta render --format json at build time and turns the result into docutils
nodes, so the page is rebuilt from the tags on every build rather than from a
file somebody remembered to update.
# conf.py
extensions = ["myst_parser", "moneta_sphinx"]
```{moneta-changelog}
```
That is the whole setup for a docs/ directory inside the repository being
documented: with no moneta_repo set, the extension walks up from the source
directory to the enclosing checkout.
Installing it¶
moneta is distributed as a nix flake, so overlays.default is how another
project takes it:
{
inputs.moneta = {
url = "gitlab:terryp/moneta";
inputs.nixpkgs.follows = "nixpkgs";
};
outputs = {nixpkgs, moneta, ...}: let
pkgs = import nixpkgs {
system = "x86_64-linux";
overlays = [moneta.overlays.default];
};
in {
packages.x86_64-linux.docs-env = pkgs.buildEnv {
name = "docs-env";
paths = [
(pkgs.python3.withPackages (ps: [
ps.sphinx
ps.moneta-sphinx
]))
pkgs.moneta
];
};
};
}
The overlay carries both halves because a site needs both: moneta-sphinx
goes into every python version’s package set, so it joins the same
interpreter as the site’s own Sphinx, and moneta goes on PATH, because the
extension renders the page by running it. A site with the extension and no
binary fails the build rather than publishing an empty changelog, but it
fails all the same.
ps.moneta-sphinx.optional-dependencies.myst is MyST, which the default
moneta_body_parser needs; a site that already installs myst-parser for
its own pages has it.
The overlay reaches every interpreter in the package set, not just the default
one, so python312Packages.moneta-sphinx is as real as
python3Packages.moneta-sphinx and a site pinned to an older python needs
nothing else.
Directive options¶
Option |
|
|---|---|
|
|
|
render only these kinds, comma- or space-separated |
|
render only entries carrying one of these scopes |
|
|
|
leave out the Unreleased section |
|
read a different repository, relative to the source directory |
|
the module to render, in a repository with modules |
Filtering happens after moneta has run, not as flags to it, so a site with several changelog pages — one per scope, say — is still one subprocess.
:heading-depth: is a depth rather than a level because the level the headings
come out at is decided by where the directive sits in the page, which docutils
resolves and the extension cannot. What it controls is how many of the two
generated levels are real headings:
2A section per version and a section per kind. Everything is linkable and everything is in the sidebar.
1A section per version; the kinds become rubrics. This is what a project with fifty releases wants, rather than three hundred sidebar entries.
0No headings at all, for embedding the changelog under a page’s own. The version anchors still exist, so cross-references keep working.
Modules¶
In a repository with modules (see the Modules section of
Configuration), each page renders one module. Set
:module: on the directive, or set moneta_module in conf.py for a site
that documents one module:
```{moneta-changelog}
:module: core
```
Each module is a separate run of moneta, and each page is rebuilt only when
its module’s changelog changes. A page with no module fails the build, as does
a moneta_json document that was rendered for a different module.
$MONETA_MODULE does not reach moneta from a docs build: only conf.py and
the page select the module.
To refer to a module’s release, use its tag: {moneta:version}`core/v1.2.0`.
Cross-references¶
Every rendered version is an object in the moneta domain:
The fix shipped in {moneta:version}`v1.2.0`.
The tag prefix is optional — {moneta:version}`1.2.0` resolves too — since
which form is the version’s name is a property of the project’s moneta.tag-prefix
and prose should not have to know it. With nitpicky = True, a reference to a
release the site no longer renders fails the build.
Configuration¶
Value |
Default |
|
|---|---|---|
|
|
the binary to run |
|
|
the repository to read; relative paths resolve against the source directory |
|
|
read this file instead of running moneta |
|
|
extra arguments for |
|
|
|
|
|
the default for |
|
|
the default for |
Entry bodies are Markdown, so the default parses them with MyST; each body is
parsed into a document of its own rather than through the host page’s state
machine, which on a Markdown page would leave anything generated as literal
text. A project whose fragments are reStructuredText sets
moneta_body_parser = "rst".
moneta_json is the escape hatch for a build that cannot run git — a hermetic
package build, or a shallow CI checkout, where moneta would correctly refuse.
Render the document in a job that has the full history and carry the file into
the one that does not.
Incremental builds¶
Rebuilding the changelog page on every build is wasteful; not rebuilding it when it has changed publishes a stale one. Two mechanisms, because neither is enough alone:
Every fragment file and
omniblack.yamlis a dependency of the page, so editing an entry rereads it the way editing any source file does.Creating a tag changes which release an entry belongs to without touching any file, which no dependency can catch. So the extension also hashes the document on
env-get-outdatedand compares it with what the page last rendered.
Watching .git/HEAD and .git/packed-refs as dependencies was the obvious
alternative, and it is wrong often enough to matter: a ref may be loose or
packed, and .git is a file rather than a directory inside a worktree.
The hash deliberately leaves out repo.head, so an ordinary commit — one that
adds no entry and no tag — rebuilds nothing.
Failing loudly¶
A changelog that renders empty, or short by a release, looks exactly like a correct one. Nobody reading the page can tell. So each of these stops the build rather than producing a page:
monetaexiting non-zero, including its refusal to read a shallow clone. The child’s stderr is reported verbatim.a
schema_versionthe extension was not written for.:versions:naming a release that is not there.moneta_body_parser = "myst"withmyst_parsernot loaded.