OpenParable
Skip to content
← Back to skills

Sphinx RST Conventions

Documents

Sphinx RST Conventions is an Agent Skill for documents published in the RocketPy-Team/RocketPy repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/RocketPy-Team/RocketPy/blob/HEAD/.agents/skills/sphinx-docs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/sphinx-rst-conventions, 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.

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