What the agent does
The agent reads how the docs are built in all three places they are built before it adds anything. In a library like pallets/click, pyproject.toml has a docs dependency group with myst-parser, pallets-sphinx-themes, sphinx, sphinx-tabs and sphinxcontrib-log-cabinet, and a [tool.tox.env.docs] whose one command is sphinx-build -E -W -b dirhtml docs docs/_build/dirhtml. .readthedocs.yaml takes full control of the build and runs uv run --group docs sphinx-build -W -b dirhtml docs $READTHEDOCS_OUTPUT/html on Python 3.13. uv.lock pins Sphinx by Python version, 8.1.3 on 3.10 and 9.1.0 on the newest. docs/conf.py lists seven extensions, autodoc, extlinks, intersphinx, sphinx_tabs.tabs, sphinxcontrib.log_cabinet, pallets_sphinx_themes and myst_parser, and uses the click theme. docs/index.md is MyST Markdown with six {toctree} blocks under headings: one bare block with faqs, then Tutorials, How to Guides, Conceptual Guides, General Reference with twenty pages, and API Reference with api, a page that is a sheet of autoclass directives rendered from docstrings. .github/workflows/tests.yaml ignores docs/**, so only Read the Docs builds the docs today, and -W makes any warning fatal there.
The agent writes the generator as a local extension, docs/_ext/llms_txt.py, and adds _ext to sys.path and llms_txt to extensions in conf.py, because a project with its own theme and directives is better served by thirty lines it owns than by another pinned package. The extension connects to build-finished and does its work only when the builder is text, Sphinx's own plain-text renderer, which is what turns the api page's directives and the theme's click:example and click:run blocks into readable text. It reads the section headings and the toctree entries from docs/index.md in order, takes each page's title from env.titles, and writes llms.txt with # Click from the project name, the first paragraph of index.md as a blockquote, and one ## section per heading with a linked line per page. It writes llms-full.txt by concatenating the builder's <docname>.txt output files in the same order, each under a # <title> heading. Both land in the builder's outdir, and the links point at https://click.palletsprojects.com/<docname>/, the dirhtml addresses conf.py's html_theme serves.
The build commands then grow by one step each. The tox docs env gets a second command, sphinx-build -E -W -b text docs docs/_build/text, and a third that copies the two files into docs/_build/dirhtml/; .readthedocs.yaml gets the same text build and copies them into $READTHEDOCS_OUTPUT/html/ so the live site serves /llms.txt. Because -W is on everywhere, the agent makes sure the text builder raises no warning the dirhtml builder does not, and that the extension registers with parallel_read_safe so Sphinx does not warn about it. requires-python >=3.10 is untouched, and the extension uses nothing newer than that.
To check it, the agent runs uv run --group docs tox run -e docs in its sandbox and reads docs/_build/dirhtml/llms.txt, confirms it names every page in index.md's toctrees and no file outside them, greps llms-full.txt for a class signature from the rendered api page to confirm autodoc content came through, and compares the dirhtml output against a build from the current branch to show the HTML did not change. It adds a docs.yaml workflow that runs the same tox env on pull requests touching docs/** or pyproject.toml, pinned the way the other workflows pin their actions, so a change that breaks the files fails before Read the Docs sees it.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add llms.txt and llms-full.txt to this Sphinx documentation site. Read pyproject.toml, especially the docs dependency group and the tox docs env, .readthedocs.yaml, docs/conf.py, docs/index.md and docs/api.md, and the workflows under .github/workflows first. Write a local extension in docs/_ext that runs on build-finished for the text builder only: build llms.txt from the headings and toctree entries of index.md with the project name, a blockquote and one linked line per page, and llms-full.txt from the text builder's output files in the same order under per-page headings. Register it in conf.py. Add a text build and a copy of the two files to the tox docs env and to the Read the Docs build so the live site serves them. Keep -W on and let no new warning through. Add a small docs workflow that runs the tox docs env on pull requests touching docs or pyproject.toml, pinned like the existing workflows. Run the tox env, show llms.txt, check a signature from the API page is in llms-full.txt, confirm the dirhtml output is unchanged, and open a pull request with the output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds docs/_ext/llms_txt.py and .github/workflows/docs.yaml, and changes docs/conf.py, the docs env in pyproject.toml and .readthedocs.yaml. Its description pastes the generated llms.txt in full, the API section of llms-full.txt down to the first class signature, the tox output with its warning count, and a listing of the pages per section beside the toctrees in index.md so a reviewer can see nothing was dropped.
The new docs workflow runs on the pull request itself, so the first green check is the same command Read the Docs will run, and the Read the Docs preview for the branch serves /llms.txt at the site root. The run's record keeps the diff between the two dirhtml builds, which is empty.
Before merging, a reviewer edits the blockquote, decides whether the bare faqs toctree should sit under its own heading or at the top, and whether llms-full.txt is wanted at all for a site whose API page is long. The pages, the theme and the HTML build are unchanged.
Run it on every Sphinx site without an llms.txt
A team with several Sphinx projects sends this body once per repository to POST /o/{org}/sessions, each with its own repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own conf.py and build commands: a project with reStructuredText sources gets the toctree parsed from index.rst, one that builds with a Makefile gets the text build added as a target, and one hosted on GitHub Pages gets the copy step in its deploy workflow instead of a Read the Docs file.
Once the extension is registered, no further run is needed when pages change, because every docs build regenerates both files. A webhook_url on the key reports each run.completed with the pull request in result, and a run.failed names a project whose strict build broke, for instance one where the text builder warns on a directive the HTML builder accepts.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A Sphinx site with its own theme, its own directives and -W on three build paths does not take a drop-in file. The agent reads the dependency group, the tox env, the Read the Docs job and the toctrees, writes an extension that fits them, and proves in its sandbox that the strict build still passes and the HTML did not move.
The tox output, the generated files and the empty HTML diff stay with the run and are quoted in the pull request. Several documentation sites can get the same change at once, each in its own sandbox, each with its own evidence.
Frequently asked questions
Why the text builder and not the Markdown sources?
Because the pages that matter most are the ones rendered from code. docs/api.md is a list of autoclass directives, and the click:example blocks in the guides are custom directives from the theme; the Markdown source of those pages says almost nothing. Sphinx's text builder renders them the way the HTML builder does, as plain text, so llms-full.txt carries the real signatures and docstrings.
Why a local extension instead of a published one?
The project pins everything through uv.lock and builds with -W, so one more package means one more pin and one more source of warnings across three Sphinx versions. Thirty lines in docs/_ext/ use only Sphinx's own events and environment, work the same on 8.1.3 and 9.1.0, and are easy to delete. The pull request says so and names the published alternatives if you prefer one.
Does this change the HTML site?
No. The extension does nothing when the builder is dirhtml, and the agent diffs the dirhtml output against a build from the current branch to show it is byte-for-byte the same. The only new things the live site serves are /llms.txt and /llms-full.txt.
Will Read the Docs pick it up?
Yes, because .readthedocs.yaml already overrides the build steps, and the agent adds the text build and the copy there. The pull request's Read the Docs preview is the place to confirm it, and the new docs workflow runs the same tox env on every pull request so a break shows up before the preview builds.
More Sphinx jobs
The same job on other stacks
- Add llms.txt to a Starlight Docs Site (Starlight)
- Add llms.txt to a VitePress Blog (VitePress)
- Add llms.txt to a Zola Site With a Feed Template (Zola)