# Add llms.txt to a Sphinx Docs Site

Yes. An agent adds a Sphinx extension that writes llms.txt from your toctree and llms-full.txt from the text builder, wired into tox and Read the Docs, in a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-llms-txt/sphinx/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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

- [Add Mermaid Diagrams to Sphinx Docs](https://getrush.ai/run/add-mermaid-diagrams/sphinx/)
- [Add Open Graph Tags to Sphinx Docs](https://getrush.ai/run/add-open-graph-tags/sphinx/)
- [Add PDF Export to Sphinx Docs](https://getrush.ai/run/add-pdf-export/sphinx/)

## The same job on other stacks

- [Add llms.txt to a Starlight Docs Site](https://getrush.ai/run/add-llms-txt/starlight/)
- [Add llms.txt to a VitePress Blog](https://getrush.ai/run/add-llms-txt/vitepress/)
- [Add llms.txt to a Zola Site With a Feed Template](https://getrush.ai/run/add-llms-txt/zola/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
