What the agent does
The agent reads the docs toolchain first. In a project laid out like pallets/click, docs/conf.py lists the extensions sphinx.ext.autodoc, sphinx.ext.extlinks, sphinx.ext.intersphinx, sphinx_tabs.tabs, sphinxcontrib.log_cabinet, pallets_sphinx_themes and myst_parser, uses the click theme from pallets_sphinx_themes, and keeps html_static_path = ["_static"] with only the project's logo and icon in it. The docs dependencies are a uv dependency group in pyproject.toml: docs = ["myst-parser", "pallets-sphinx-themes", "sphinx", "sphinx-tabs", "sphinxcontrib-log-cabinet"], resolved in uv.lock. The build is defined twice and must stay in sync: the tox docs environment runs sphinx-build -E -W -b dirhtml docs docs/_build/dirhtml, and .readthedocs.yaml runs uv run --group docs sphinx-build -W -b dirhtml docs $READTHEDOCS_OUTPUT/html. .github/workflows/tests.yaml ignores docs/**, so the docs build is not part of the test matrix. The pages are MyST Markdown; shell examples use ```console fences, and most of their lines start with $ .
The package is sphinx-copybutton, currently 0.5.2, and the extension name is sphinx_copybutton. The agent adds it with uv add --group docs sphinx-copybutton, which updates both pyproject.toml and uv.lock, and appends "sphinx_copybutton" to extensions in conf.py. With no further settings the button copies the whole block, prompts included, which is wrong for a console block: a reader pasting $ pip install click into a shell gets a syntax error on the $.
So the configuration is about prompts. The agent sets copybutton_prompt_text to the regular expression the extension's own documentation recommends, r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: ", with copybutton_prompt_is_regexp = True, so $ and >>> prompts are stripped and only the prompted lines are copied, leaving output lines out. It does not set copybutton_exclude to .gp, because that selector-based exclusion conflicts with the pattern approach and the docs say so. It checks that the fences really are console rather than bash, since Pygments only tags prompts in console lexers, and rewrites a fence where the language is wrong. The extension's own CSS and copybutton.js are copied into _static by the build; nothing is added to the repository's _static directory.
The proof is the strict build. The agent runs uv run --group docs tox run -e docs, which is the same -W build Read the Docs runs, and treats a warning as a failure the way CI would. It then opens docs/_build/dirhtml/quickstart/index.html and confirms the page references _static/copybutton.js and that a console block's prompts are inside .gp spans, which is what the JavaScript strips at click time. The theme's layout is checked for the button overlapping the right edge of a div.highlight; if it does, a small rule in a new docs/_static/custom.css registered through html_css_files is the only addition, and the pull request shows the before and after.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a copy button to the code blocks in this Sphinx documentation with sphinx-copybutton. Read docs/conf.py, pyproject.toml (the dependency groups and the tool.tox docs environment), uv.lock, .readthedocs.yaml and a few pages under docs/ first to see how console examples are written. Add sphinx-copybutton to the docs dependency group with uv add --group docs, add sphinx_copybutton to extensions, and set copybutton_prompt_text to the regular expression the extension documents for shell, Python and IPython prompts with copybutton_prompt_is_regexp = True, so prompts are stripped and output lines are not copied. Do not set copybutton_exclude for prompts. Fix any fence that uses bash where console is meant. Build with uv run --group docs tox run -e docs, confirm the built quickstart page loads copybutton.js and that prompts are in .gp spans, and open a pull request that quotes the build output and lists the configuration you set with one sentence on why.",
"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 changes pyproject.toml (one entry in the docs group), uv.lock, and docs/conf.py (one extension and two options), plus any fence whose language was corrected. Its description quotes the strict sphinx-build -W output from the tox environment, explains that the prompt regex strips $ and >>> and skips output lines, and includes a screenshot or the rendered HTML of one console block with the button.
A reviewer checks that the lock file changed only for the new package and its dependencies, that no _static files were vendored, and that .readthedocs.yaml needs no change because it installs the same docs group. They may prefer the button to copy output lines too, which is copybutton_only_copy_prompt_lines = False.
After merge, every code block on the site gets a button, console examples paste cleanly into a shell, and the Read the Docs build runs with the same warnings-as-errors setting it had before.
Run it on every pull request that touches docs/
An automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize reads each changed page for a fenced block whose language is bash or shell but whose lines start with $ , which the copy button would copy with the prompt. An automation's run is read-only, so it posts a review comment naming the fence and the console language it should use.
An organisation with many Sphinx projects starts one run per repository from a handler on its own server, sending this body to POST /o/{org}/sessions with the repository in resources and a request_id that is a UUID v5 of the repository name, so a retried loop returns the run it already started. Each run reads its own conf.py and installs into whatever the project uses, a uv group, a requirements.txt or a tox deps list.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The extension is a one-line install, and the part worth getting right is the prompt handling, which depends on how a project writes its examples. An agent that reads the pages, counts the console fences and tests the strict build in its own sandbox gets the configuration that fits, and the build output stays with the pull request.
Documentation builds with -W turn every warning into a failure, and a theme can place the button badly. Running the real build and opening the real HTML in a sandbox, rather than trusting a snippet, is what makes the pull request safe to merge without a preview deploy.
Frequently asked questions
Will the button copy the $ prompt?
Not with the configuration the agent sets. copybutton_prompt_text is a regular expression matching $ , >>> , ... and IPython prompts, with copybutton_prompt_is_regexp = True, so prompts are removed and only prompted lines are copied. Output lines in a console block are left out.
Does Read the Docs need a change?
No. .readthedocs.yaml installs the docs dependency group with uv and runs sphinx-build -W, so adding the package to that group is enough. The agent runs the same strict build locally through the tox docs environment.
Why not exclude .gp prompts with copybutton_exclude?
The extension documents that selector-based exclusion conflicts with the pattern-based settings, and it also depends on every fence using a console lexer. The regex approach works for Python REPL and IPython examples as well, which this project's pages contain.
Does this add files to the repository?
Only the dependency and the configuration. The extension's copybutton.js and CSS are copied into the build output by Sphinx, not into docs/_static. A theme-specific CSS tweak, if needed, is the one file the agent would add, and the pull request would show it.
More Sphinx jobs
More jobs like this: Hand off a long task
- Add CORS to an Actix Web API (Actix Web)
- Add CORS to an aiohttp App (aiohttp)
- Add CORS to an Axum API (Axum)