# Sphinx RST Conventions

> Use when writing or editing docs/**/*.rst. Covers Sphinx/reStructuredText conventions, cross-references, toctree hygiene, and RocketPy unit/reference-frame documentation requirements.

- Skill: `rocketpy-team/sphinx-rst-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rocketpy-team/sphinx-rst-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rocketpy-team/sphinx-rst-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: rocketpy-team (https://skillmd.com/u/rocketpy-team)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rocketpy-team/sphinx-rst-conventions

---

# Sphinx and RST Guidelines

- Follow existing heading hierarchy and style in the target document.
- Prefer linking to existing documentation pages instead of duplicating content.
- Use Sphinx cross-references where appropriate (`:class:`, `:func:`, `:mod:`, `:doc:`, `:ref:`).
- Keep API names and module paths consistent with current code exports.
- Document physical units and coordinate/reference-frame conventions explicitly.
- Include concise, practical examples when introducing new user-facing behavior.
- Keep prose clear and technical; avoid marketing language in development/reference docs.
- When adding a new page, update the relevant `toctree` so it appears in navigation.
- Use RocketPy docs build workflow:
  - `make build-docs` from repository root for normal validation.
  - If stale artifacts appear, clean docs build outputs via `cd docs && make clean`, then rebuild.
- Treat new Sphinx warnings/errors as issues to fix or explicitly call out in review notes.
- Keep `docs/index.rst` section structure coherent with user, development, reference, technical, and
  examples navigation.
- Do not edit Sphinx-generated scaffolding files unless explicitly requested:
  - `docs/Makefile`
  - `docs/make.bat`
- For API docs, ensure references remain aligned with exported/public objects and current module paths.

See:
- `docs/index.rst`
- `docs/development/build_docs.rst`
- `docs/development/style_guide.rst`
- `docs/reference/index.rst`
- `docs/technical/index.rst`