Documentation contributor guide

The Sphinx source uses MyST Markdown. Documentation is organized by reader question, not package directory:

• introduction/: purpose, scope, and principles;

• getting-started/: installation and first run;

• data-model/: scientific container semantics;

• processing/: pipeline concepts and local operation;

• modules/: curated workflow/science guides;

• server/: client-server operation;

• examples/: small examples and the external instrument catalogue;

• reference/: exact generated and hand-written reference;

• development/: contribution guidance and design records; and

• project/: changelog, authors, citation, and license.

Authoring rules

• Put tutorials, explanations, how-to guidance, and exact reference in their respective sections rather than combining them into one long page.

• Link to generated module pages instead of copying configuration tables.

• Keep instrument notebooks, pipeline YAML, manifests, and data in MoDaCor-examples.

• Use repository-relative links and stable Sphinx labels; never publish absolute workstation paths.

• Add an old-to-new Rediraffe entry when moving a published page.

• Update the navigation landing page and “where next” links when adding a new section.

Build locally

uv venv --python 3.12 .venv-docs
source .venv-docs/bin/activate
uv pip install -e ".[docs]"
python scripts/generate_module_doc.py \
  --all --output-dir docs/reference/modules \
  --index docs/reference/modules/index.md --check
sphinx-build -E -W --keep-going -b html docs dist/docs

Or run tox -e docs. Use tox -e linkcheck for external and internal link validation.

When changing public steps, regenerate the checked-in module pages without --check, review the diff, then run the check form.