Updating the Docs¶
The documentation is built with MkDocs and the
Material theme, with API
reference pages rendered from docstrings by
mkdocstrings. The site is deployed to
GitHub Pages from CI on every push to main that touches the docs.
Layout¶
mkdocs.yml— site configuration and navigationdocs/— all pages (Markdown)docs/api/— mkdocstrings stubs for the Python provider packagesdocs/requirements.txt— the doc-build dependencies.github/workflows/docs.yml— build + deploy pipeline
Local preview¶
Before opening a pull request, verify the strict build passes — CI runs the same command, and warnings are errors there:
Adding a page¶
- Write the Markdown file under
docs/. - Add it to the
nav:section ofmkdocs.ymlin the appropriate section. - Run
mkdocs build --strict— it catches broken internal links.
Internal links use relative Markdown paths (e.g. [Slurm](slurm.md)), so
they work both on GitHub and on the rendered site.
API reference pages¶
Each docs/api/<package>.md page is a thin stub containing a
::: <module> directive; mkdocstrings reads the source under
providers/src (see the paths option in mkdocs.yml) and renders the
docstrings. Improving a provider's docstrings therefore improves the
published API reference with no doc edits at all. Docstrings use the Google
style.
What CI does¶
.github/workflows/docs.yml triggers on pushes to main that touch
docs/, mkdocs.yml, or the provider sources. It installs
docs/requirements.txt plus the providers package, runs
mkdocs build --strict, uploads site/ as the Pages artifact, and deploys
it. There is no gh-pages branch to manage.