Writing And Building Docs
Documentswriting-and-building-docsWriting And Building Docs is an Agent Skill for documents published in the aiidateam/aiida-core repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when writing, editing, or building documentation files (`.md`, `.rst`) under `docs/`.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/aiidateam/aiida-core/blob/HEAD/.claude/skills/writing-and-building-docs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/writing-and-building-docs, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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