Contributing to documentation

How to propose documentation changes and keep them consistent with the code.

---

What lives where

Audience	Entry
All users	Documentation home, Getting started, Learning paths
Assistants / LLMs	Using with LLMs, MCP, repo-root AGENTS.md
Data / metadata	Data setup, Experiment details
Developers	Architecture, Developer guide, Testing
Auto API	generate_api_docs.py (writes advanced/api/ on each build)

---

Workflow

1. Small fixes (typos, broken links) — open a PR directly.
2. New behavior — update docstrings first (generated API picks them up), then narrative Markdown if needed.
3. Large restructures — discuss in an issue first if navigation changes are broad.

---

Reporting issues

Use GitHub Issues with label documentation when possible. Include:

• Page or file path (e.g. docs/src/content/docs/guides/data-setup.mdx)
• What you expected vs what you saw
• Environment (OS, Python version, install method)

---

Review checklist (for maintainers)

• npm run build succeeds under docs/
• New public API has docstrings (interrogate)
• Spot-check Pipeline API (generated)

---

Style

• Prefer clear headings and short paragraphs.
• Use code fences with language tags for Python and shell.
• Avoid duplicating long signatures; link to Pipeline API or API & data formats instead.