ADR-0001: Sphinx and reStructuredText for Project Documentation¶
- Status:
Accepted
- Date:
2026-10-01
Note
Since ADR-0027: Tenancy Model — Platform, Organization, Project, customers are called organizations and the installation-wide level formerly called the organization is the platform; this record keeps the terms of its time.
Context¶
Ballet is documentation-driven: documentation is written alongside code by humans and agents, and must stay verifiable. Cross-references between concepts, architecture and ADRs must not silently break. The documentation must be publishable as a static site.
Decision¶
Project documentation is a Sphinx site written in reStructuredText under
docs/. docs/ is a self-contained uv Python project. make
docs-check runs a strict build (warnings are errors) and a link check,
and must pass in CI.
This covers documentation about Ballet. Knowledge Ballet manages for customers lives in the Knowledge service.
Alternatives Considered¶
Markdown with MkDocs¶
Advantages:
Familiar syntax; very low barrier.
Disadvantages:
Weaker cross-reference checking; broken links are easier to miss.
Markdown files without a site generator¶
Advantages:
Zero tooling.
Disadvantages:
No build-time verification, no navigation, no diagrams.
Decision Criteria¶
Link integrity, verifiability in CI, diagram support, maintainability.
Rationale¶
Sphinx’s roles (:doc:, :ref:) are resolved at build time, so a
strict build catches broken references — important when agents write
much of the documentation.
Consequences¶
Positive¶
Broken references fail CI.
Negative¶
reStructuredText is less familiar than Markdown.
Risks¶
None significant.
Follow-up¶
Publish the site (e.g. GitHub Pages) once the repository is hosted.