About this documentation

About this documentation#

This documentation is built using Sphinx with myst-parser.

The theme used is sphinx-book-theme.

How to contribute#

The documentation is written in myst-parser 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 shortcut to add links to the monorepo at Github, by prefixing gh: plus the relative path. For example:

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

Produces this link: e2e workflow

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

How to build the documentation#

From the root directory run

$ make docs

This will run sphinx-build using uv run with the docs requirements.

It should exit without error nor warnings.

If you want to check everything looks ok, open the generated html in the browser.

$ make docs-open

Also you can build the documentation in epub with make docs-epub

How the documentation is published online#

  • GitHub Actions workflow: [](gh:.github/workflows/cd.yml) publishes docs to GitHub Pages.

  • Triggers:

    • On releases (PyPI publish + docs deploy).

    • Manual via workflow_dispatch (used for the initial docs build and any ad-hoc redeploy).

  • To trigger manually from your repo: gh workflow run cd.yml --ref main (requires gh CLI auth) or use the Actions UI.

Contents