Documentation#
Building#
From the repository root, in a Python environment with PyTorch (a CPU build is enough):
python -m pip install -r docs/requirements.txt
./scripts/build_docs.sh
Open docs/_build/html/index.html. The build imports bartorch from src/,
which needs torch but not the compiled library, and renders the gallery
without running it. Warnings are errors, as in the documentation workflow.
To run the gallery, build the library first (see Toolchain), then:
./scripts/build_docs.sh --execute
A failing example fails the build. Examples with the optional_ prefix are
rendered but not run; to run them too, install docs/requirements-examples.txt
and pass
-D sphinx_gallery_conf.filename_pattern='/(plot_|optional_)' to Sphinx.
--online fetches intersphinx inventories. Check external links with
python -m sphinx -b linkcheck docs docs/_build/linkcheck.
Pages and the reference#
Pages are Markdown, parsed by MyST; a directive is written as a fenced block,
and reStructuredText only inside {eval-rst}. Each page of the API reference
(docs/api/) is a set of sections, each an autosummary table of the names it
documents; autosummary writes a page per name into docs/api/generated/, and
autodoc renders its docstring. tests/test_docs.py fails when a public name is
missing from the reference or the reference lists one that is not public.
A command without a hand-written wrapper is built at import from BART’s catalogue, with BART’s help as its docstring; its reference page is rendered from that docstring like any other.
Gallery examples#
Place a standalone script in a numbered subsection of docs/gallery_src/: plot_
for core CPU examples, optional_ for ones needing optional libraries. Begin
with a module docstring holding a title, the objective, prerequisites and
scope; separate narrative and code with # %% blocks. A new subsection needs
a GALLERY_HEADER.md.
Use fixed seeds, small synthetic inputs and visible results, and include a check against something outside BART, such as a closed form or an adjoint identity. No downloads, hidden datasets, blanket exception handling or installation commands.
Docstrings#
Docstrings are NumPy style and written for a developer reading the code.
State what is not obvious from the name, the signature and the annotations: units, coordinate frames, composition order, invariants, side effects, preconditions, special return values, and behaviour a maintainer could break by accident.
Do not restate the signature, narrate the implementation, or document a parameter with its own name. List a parameter only when its entry adds something.
A module docstring states the module’s responsibility in a sentence or a few. Design rationale belongs in
AGENTS.mdor in a comment beside the code it explains.A private helper gets a docstring only for a contract that is not obvious.
Precision over brevity: a short paragraph for a real invariant is better than an ambiguous line.