About these docs

Conventions for anyone writing documentation in this repository. If you are here to use Sphinx Lens, you want Getting started instead.

Documentation ships with the change

Docs and implementation live in the same repository and evolve in the same pull request. A behavioral change without a documentation change is an incomplete change, in the same way a behavioral change without a test is.

Broken docs break the build

make docs runs Sphinx with warnings as errors, so a dead cross-reference, a malformed directive, or an orphaned page fails CI rather than shipping quietly.

Run the examples, do not retype them

Hand-written command output rots. Where a chapter shows a command, prefer richterm, which runs it during the docs build, and sphinxcontrib-mermaid for diagrams that live as text.

Numbers recorded from long or expensive runs, such as the corpus measurements, are the exception. Those are transcribed on purpose, with the commit they came from, so a reader can re-verify them deliberately.

Order the chapters as a reading path

The chapter order in the sidebar is a reading order: get it running, look something up, understand why it is built this way, see what it does under load, contribute. Diataxis informed that shape, giving a tutorial, reference material, and explanation each one job to do. It stays a writing tool: the reader should never have to know about it. Do not label chapters with their Diataxis mode, and do not split the table of contents into one group per mode.

Keep environment variable definitions in Environment variables using the glossary directive, and refer to them with {term} (for example PYTHONPATH) so the definition has exactly one home.

Publishing is automated

gh:.github/workflows/cd.yml deploys to GitHub Pages: release and manual runs publish the canonical site, and pull requests that touch docs publish a preview under https://mgaitan.github.io/sphinx-lens/_preview/pr-<PR_NUMBER>/.

Manual dispatch through the gh CLI usually authenticates with GH_TOKEN; the workflow internals use GITHUB_TOKEN.

These conventions come from the repository template; the reasoning behind them is written up in Opinionated Python project scaffolding.