About this documentation

About this documentation#

This documentation is built using Sphinx with myst-parser.

The theme used is sphinx-book-theme.

The project itself was created and is still maintained with python-package-copier-template.

How to contribute#

The documentation is written in MyST Markdown.

The MyST extensions colon_fences, linkify, and deflist are enabled, and you can also use the extra content blocks from our theme.

In addition, you can use all the directives available in Sphinx, as explained in this guide.

We also ship richterm to capture CLI output as SVG in the docs.

Including diagrams#

We support Mermaid diagrams, powered by sphinxcontrib-mermaid:

        graph LR;
    Hi-->there;

with this syntax:

```{mermaid}
:align: center
graph LR;
  Hi-->there;
```

Linking to the repo#

There is a shortcut for links to the GitHub repository by prefixing gh: plus the relative path. For example:

[ci workflow](gh:.github/workflows/ci.yml)

Produces this link: ci workflow

Check myst_url_schemes at docs/conf.py for details on how it is implemented.

How to build the documentation#

From the project root run:

make docs

This runs sphinx-build using uv run with the docs requirements. It should exit without errors or warnings.

If you want to check everything looks right in a browser, run:

make docs-open

You can also build EPUB output with make docs-epub.

How the documentation is published online#

  • GitHub Actions workflow: .github/workflows/cd.yml publishes docs to GitHub Pages.

  • Triggers:

    • on releases,

    • on pull requests that change docs-related files, publishing a preview under /_preview/pr-<PR_NUMBER>/,

    • manually via workflow_dispatch.

  • To trigger it manually from your repo: gh workflow run cd.yml --ref main or use the Actions UI.

Contents