About the Documentation

This repository documents both the template itself and the documentation scaffold generated for new projects. The goal of this page is to explain that baseline so it stays coherent as the template evolves.

Structure

Generated projects ship documentation as a first-class artifact and follow Diataxis:

Chapter	Type	Purpose
getting_started.md	Tutorial	Onboarding, first steps
development_workflow.md	How-to	Common operational tasks
configuration.md	Reference	Factual lookup, env vars glossary
about_the_docs.md	Explanation	Rationale and doc conventions

This template repository adds extra pages around that core set, such as template maintenance, CLI behavior, and adoption notes. Those pages document the template itself rather than the generated project skeleton.

Tooling

• Sphinx + MyST — docs written in Markdown, built with Sphinx.

• sphinx-book-theme — the visual theme used by the generated documentation.

• richterm — CLI captures generated at build time, not copied by hand.

• sphinxcontrib-mermaid — diagrams defined as code.

Build locally with:

make docs
make docs-open

The build runs in warning-as-error mode, so broken links or directives are caught early.

CI routes checks by changed paths: documentation edits build docs, workflow edits run actionlint, and template or Python edits render the generated project and run its QA bundle.

Documentation for LLMs

The HTML build generates llms.txt using sphinx-llms-txt. It lists documentation pages with links to their published Markdown sources under _sources/. The index is included in the existing GitHub Pages deployment; no separate publishing step is needed.

Source links are relative to the index, so they also work under project paths and PR preview directories. Inspect docs/_build/html/llms.txt after make docs.

These are the original MyST sources, including their directives. The extension also generates llms-full.txt by concatenating sources. That file retains MyST includes and CLI capture directives, so it is not a self-contained export of the rendered documentation. Use llms.txt to find the relevant source pages.

New generated projects include this configuration. For existing projects, see Maintain the Template to enable it while preserving customized documentation.

Conventions

• Environment variables should be defined once in configuration.md using the Sphinx glossary directive and referenced everywhere else with {term}`VAR_NAME`.

• Any behavior or feature change should update the relevant doc page in the same PR.

• Generated projects should prefer adding new sections over rewriting seeded ones, to keep copier update diffs clean.

Copier treats generated README.md and docs/** files as project-owned after their initial creation. Template updates add missing documentation pages but do not overwrite existing ones. Review documentation changes in the template when you want to adopt improvements manually.

Publishing

GitHub Actions (defined in .github/workflows/cd.yml) deploys docs to GitHub Pages automatically:

• Release or manual dispatch publishes the canonical site.

• PRs that touch docs/ get a preview deployment under /_preview/pr-<N>/.