aiidateam Writing and building documentation for aiida-core
When writing or editing .md or .rst files under docs/:
- Write one sentence per line (no manual line wrapping): makes diffs easy to review.
- File/directory names: alphanumeric, lowercase, underscores as separators.
- Headers in sentence case (e.g., "Entry points", not "Entry Points").
- Documentation follows the Divio documentation system: tutorials (learning-oriented), how-to guides (goal-oriented), topics (understanding-oriented), reference (information-oriented).
Building the docs
uv run sphinx-build -b html docs/source docs/build/html
For live-reloading during development, use sphinx-autobuild (not a project dependency, install manually):
uv pip install sphinx-autobuild
uv run sphinx-autobuild docs/source docs/build/html