# Add a Copy Button to Sphinx Code Blocks

Yes. An agent adds sphinx-copybutton to your docs dependency group, configures prompt stripping for your console blocks, builds with -W like CI, and opens a PR.

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

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

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

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

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

- [Add Dark Mode to Sphinx Docs on the Read the Docs Theme](https://getrush.ai/run/add-dark-mode/sphinx/)
- [Add a Docs Build Check for a Sphinx Site on Every Pull Request](https://getrush.ai/run/add-docs-build-check/sphinx/)
- [Run Sphinx Doctests in CI for a Python Library](https://getrush.ai/run/add-doctest-to-ci/sphinx/)

## More jobs like this: Hand off a long task

- [Add CORS to an Actix Web API](https://getrush.ai/run/add-cors/actix/)
- [Add CORS to an aiohttp App](https://getrush.ai/run/add-cors/aiohttp/)
- [Add CORS to an Axum API](https://getrush.ai/run/add-cors/axum/)

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