LLM-Friendly Documentation#
Maverick’s documentation is built to be consumed not just by humans in a browser, but also by LLMs. Every page in the HTML docs has a corresponding Markdown version that can be fed directly into an AI assistant’s context window.
Why#
LLMs work best with clean, structured text — not HTML. When a developer wants to ask Claude or ChatGPT questions about Maverick, they should be able to point the model at the documentation without any scraping or conversion step in between.
The llms.txt standard formalises this idea: documentation sites publish a llms.txt index and per-page Markdown files alongside the normal HTML output, making the documentation machine-readable by convention.
The sphinx-llm Extension#
The sphinx-llm extension (configured via "sphinx_llm.txt" in docs/source/conf.py) hooks into the Sphinx build and generates the following files in docs/build/html/:
File |
Description |
|---|---|
|
Index listing every page with its title and a one-sentence description |
|
The entire documentation concatenated into a single Markdown file |
|
Per-page Markdown, one file per HTML page |
The per-page files follow a deterministic naming convention: the HTML file and its Markdown counterpart live in the same directory with the same base name.
docs/build/html/
├── api_reference.html
├── api_reference.html.md ← markdown twin
├── _autosummary/
│ ├── maverick.game.Game.html
│ └── maverick.game.Game.html.md ← markdown twin
└── ...
The extension works by spawning a secondary Sphinx build using the markdown builder, then renaming the output files to the .html.md convention and copying them into the HTML output directory.
Configuration#
The extension is enabled in docs/source/conf.py and requires no additional settings beyond being listed in extensions:
extensions = [
...
"sphinx_llm.txt",
]
The sphinx-llm[gen] package is listed in the docs dependency group in pyproject.toml.