Documentation guide

Documentation guide#

For developers: How to keep documentation in sync with code

Overview#

All inference documentation is maintained by hand. When you add or change configuration fields, likelihoods, EOS models, TOV solvers, or samplers, update the relevant documentation files directly. The key file is docs/inference/yaml_reference.md, which is the authoritative user-facing reference for all YAML configuration options.

Keeping Documentation in Sync#

What to Update for Common Changes#

When adding a new likelihood type:

  • Add to likelihoods/my_likelihood.py

  • Update likelihoods/factory.py

  • Add config class to config/schemas/likelihoods.py

  • Add an entry to docs/inference/yaml_reference.md under the appropriate Likelihoods category

  • Add a usage example to inference/quickstart.md if appropriate

When adding a new EOS type:

  • Add config class to config/schemas/eos.py

  • Register in transforms/transform.py

  • Add a new subsection to docs/inference/yaml_reference.md under EOS Configuration

  • Add a working example configuration

When adding a new TOV solver:

  • Add config class to config/schemas/tov.py

  • Register in transforms/transform.py

  • Update the TOV Configuration section in docs/inference/yaml_reference.md

  • Add a working example configuration

When modifying configuration fields:

  • Modify the relevant file under config/schemas/

  • Update the corresponding entry in docs/inference/yaml_reference.md

  • Update quickstart.md if the change affects the quick start workflow

When adding a new sampler:

  • Implement the sampler and add it to SAMPLER_REGISTRY

  • Add config class to config/schemas/samplers.py

  • Add a new subsection to docs/inference/yaml_reference.md under Samplers

  • Document when to use it and any important caveats

YAML Reference Structure#

The docs/inference/yaml_reference.md file is organised into sections that mirror the top-level keys of a JESTER config file:

  • Run Options — seed, dry_run, validate_only, debug_nans

  • EOS Configuration — one subsection per EOS type

  • TOV Configuration — one subsection per TOV solver

  • Prior Configuration — specification_file

  • Likelihoods — grouped by category (GW, X-ray, Radio, Nuclear, Generic, Prior-Only)

  • Samplers — one subsection per sampler

  • Data Paths — optional path overrides

  • Postprocessing — plot generation options

  • Complete Examples — full working configs

  • Validation Rules — Pydantic constraints summary

Each subsection uses a collapsible ::::{dropdown} block containing a YAML snippet with inline comments, followed by a Field Details bullet list.

Documentation Structure#

docs/
├── index.rst                          # Main entry point
├── conf.py                            # Sphinx configuration
│
├── User Guide
│   ├── inference/quickstart.md        # Quick start guide
│   └── inference.md                   # Complete reference
│
├── Reference
│   └── inference/yaml_reference.md    # Hand-maintained YAML config reference
│
├── API Reference
│   └── api/*.rst                      # AUTO-GENERATED by sphinx-autodoc
│
├── Developer Guide
│   ├── inference/workflow.md          # Development workflow
│   ├── inference_architecture.md      # System architecture
│   └── developer_guide/documentation_guide.md  # This file
│
└── _static/                           # CSS, logos, assets

Testing Documentation#

Manual Testing Checklist#

Before committing documentation changes:

  • Build passes in strict mode: uv run sphinx-build -W --keep-going docs docs/_build/html

  • Links work: click through in built HTML

  • Code examples are valid and current

  • YAML snippets match what Pydantic actually accepts

  • No new Sphinx warnings

Validating YAML Examples#

# Validate a config snippet (requires a prior file)
uv run run_jester_inference config.yaml --validate-only

Version Control#

Follow these commit message conventions:

# Updating configuration documentation
git commit -m "docs: add XYZ likelihood to yaml_reference"

# Schema change + docs update together
git commit -m "feat: add XYZ likelihood (+ yaml_reference update)"

# Fixing docs issues
git commit -m "docs: fix broken link in inference quickstart"

When a PR changes inference code, the PR checklist should include:

  • Updated docs/inference/yaml_reference.md if any config fields changed

  • Updated other manual docs if user-facing features changed

  • Added or updated working examples if the workflow changed

  • Verified the docs build passes in strict mode

Documentation Review#

When reviewing documentation PRs:

  1. Accuracy: Does the doc match what the Pydantic models actually validate?

  2. Completeness: Are all new fields and options documented?

  3. Clarity: Can a new user understand it without reading source code?

  4. Examples: Are working examples provided?

  5. Links: Do all cross-references resolve?