Documentation¶
This site is built with Zensical from the Markdown files in docs/ and the configuration in
zensical.toml. The API reference is generated from the docstrings by
mkdocstrings, which reads the source code without importing it.
Preview and build¶
The documentation tools are in the docs dependency group and need Python 3.11 or newer. They do not need YAIB's
runtime dependencies, so the commands below install only that group, into a separate environment:
This serves the site at http://localhost:8000 and rebuilds it when a page changes. To build the static site into
site/:
The separate environment keeps the docs-only sync from removing packages from the main .venv.
Publishing¶
The Documentation workflow (.github/workflows/docs.yml) builds the site for every pull request and publishes it to
GitHub Pages on every push to development.
Writing pages¶
- Add new pages to
navinzensical.toml. - Show config files and code from the repository with snippets instead of copying them, so the page cannot go stale.
Inside a code block, use the block form, with the path on its own line between two
--8<--lines: the one-line form--8<-- "path"parses as Python, and the mdformat pre-commit hook would reformat it. Paths are relative to the repository root, and a missing file fails the build. - Use admonitions (
!!! note,!!! warning) for side remarks and content tabs (=== "R") for alternatives. - Link to other pages with relative paths to their
.mdfiles.
Docstrings¶
Write docstrings in the Google style, so mkdocstrings can render the arguments and return values:
def preprocess_data(data_dir: Path, seed: int = 42) -> dict:
"""Load the cohort and split and preprocess it for one fold.
Args:
data_dir: Folder with the cohort's parquet files.
seed: Random seed for the splits.
Returns:
The preprocessed data per split and segment.
"""
To document a new module, add a icu_benchmarks.<module> line to the matching page in docs/reference/.