# Add Dark Mode to Sphinx Docs on the Read the Docs Theme

Yes. An agent adds a dark mode toggle to Sphinx docs on sphinx_rtd_theme, keeps the warnings-as-errors build and the spelling check green, and shows both modes.

[Run this on Rush](https://cloud.getrush.ai/run/add-dark-mode/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 before adding an extension. In a project laid out like pyca/cryptography, `docs/conf.py` lists `sphinx.ext.autodoc`, `autosectionlabel`, `doctest`, `intersphinx`, `linkcode`, the local `cryptography-docs` extension from `docs/_ext/`, `sphinx_rtd_theme` and `sphinx_inline_tabs`, appends `sphinxcontrib.spelling` when it imports, sets `html_theme = "sphinx_rtd_theme"` when the theme imports and `default` otherwise, and names an empty `docs/_static/`. `docs/_templates/layout.html` extends the theme's layout and adds a View on GitHub link under the sidebar title. `pyproject.toml` keeps the docs dependencies in a `docs` group of `sphinx >=5.3.0`, `sphinx-rtd-theme >=3.0.0` and `sphinx-inline-tabs`, and a `docstest` group with `sphinxcontrib-spelling`. `noxfile.py`'s `docs` session installs both groups and runs `sphinx-build -T -W -b html` into `docs/_build/html`, so a new warning fails the build, and `.readthedocs.yml` installs the same `docs` group with uv and builds with the `dirhtml` builder. The RTD theme itself ships one light palette and no toggle.

The toggle comes from the `sphinx-rtd-dark-mode` extension, which targets that theme: it adds a button to the navigation, follows the operating system's `prefers-color-scheme` until a reader chooses, and remembers the choice in the browser's local storage. The agent adds it to the `docs` group in `pyproject.toml` with a lower bound, adds `sphinx_rtd_dark_mode` to `extensions` under the same import guard the theme uses, so a build without the theme still works, and sets `default_dark_mode = False` so a reader on a light system sees the site as today. Nothing changes in `.readthedocs.yml`, because it installs the `docs` group, and the `dirhtml` builder there and `html` locally share the same theme assets.

The template override is checked, not assumed. `layout.html` only extends `sidebartitle`, and the extension injects its button elsewhere, so both render; the agent builds and opens the page in its sandbox browser to confirm the View on GitHub link and the toggle both show, and takes one screenshot per mode of `index.html` and of a page with inline tabs and a code block, since `sphinx_inline_tabs` and Pygments carry their own colors that a dark background can make unreadable. A dark palette that breaks a code block gets a small `docs/_static/dark-code.css` registered with `html_css_files`, with only the rules that page needed.

Proof is the project's own sessions: `nox -e docs`, which fails on any warning, and `nox -e docs_linkcheck`. The spelling check matters here because the extension's name and the option appear in `conf.py` only, which the checker does not read, but any new word the agent adds to a page goes through `docs/spelling_wordlist.txt`. The pull request shows the two screenshots and the sessions' output, with the installed extension version pinned to the release that built cleanly against the theme in the sandbox.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add dark mode to the Sphinx docs of this project, which use sphinx_rtd_theme. Read docs/conf.py, docs/_templates/layout.html, docs/_ext/cryptography-docs.py, pyproject.toml, noxfile.py, .readthedocs.yml and docs/development/getting-started.rst first. Add sphinx-rtd-dark-mode to the docs dependency group with a lower bound at the release you verify, add sphinx_rtd_dark_mode to extensions under the same guard that imports the theme, and set default_dark_mode to False so the site follows the reader's system until they choose. Build with nox -e docs, which treats warnings as errors, and nox -e docs_linkcheck. Open the built index page and a page with inline tabs and a code block in the sandbox browser in both modes, add a small docs/_static stylesheet through html_css_files only if a code block or tab is unreadable in dark mode, and take a screenshot of each mode. Confirm the View on GitHub link from layout.html still renders beside the toggle. Open a pull request with the session output and the screenshots.",
  "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 `docs/conf.py` and `pyproject.toml`, adds a stylesheet under `docs/_static/` only when a dark code block needed one, and leaves `docs/_templates/layout.html`, `noxfile.py` and `.readthedocs.yml` untouched. Its description pastes the `nox -e docs` and `docs_linkcheck` output and attaches the four screenshots, so a reviewer sees the toggle, the sidebar link and a dark code block without building the docs.

A reader whose system is dark gets a dark site on the first visit, anyone can flip it from the navigation bar, and the choice persists across pages and visits in that browser. The Read the Docs build picks the extension up from the same dependency group on its next run, with no change to the hosting configuration.

Before merging, a reviewer checks the dark rendering of the pages the screenshots did not cover, such as the long API tables under `docs/hazmat/`, and decides whether `default_dark_mode` should stay false or the site should open dark for everyone.

## Run it on every documentation site on the RTD theme

A team with several Sphinx sites sends this body once per repository to `POST /o/{org}/sessions` from a script, 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`: a site on Furo or another theme with a built-in dark palette gets no extension and a note, one that pins the docs dependencies in a `requirements.txt` gets the line there, and one that builds with `make html` instead of nox gets that command in the proof.

Each run opens its own pull request on its own branch. `GET /o/{org}/sessions` lists them newest first and the key's `webhook_url` receives a `run.completed` per run with the pull request in `result`, so the person who started the batch reads every build log and screenshot from one place.

## Why run it on Rush?

A theme change is judged by eye, and a docs build that treats warnings as errors is judged by the build. The agent does both in its sandbox: it builds with the project's own nox session, opens the result in a real browser, flips the mode and screenshots a code block, rather than trusting that an extension which claims to support the theme renders every element of this site.

The run keeps every command and its output and the screenshots as artifacts, so the reviewer sees both modes without installing libenchant, the Rust toolchain the package build needs, or the docs group. Several sites can be converted at once, each in its own sandbox, and one already on a theme with a dark palette gets only a note.

## Frequently asked questions

### Why not switch to Furo or another theme with dark mode built in?

Because a theme switch changes every page's layout, the sidebar override in `docs/_templates/layout.html` and the look readers know, and needs a review of its own. The extension adds a toggle to the theme already in `conf.py` and can be removed by deleting two lines.

### Does Read the Docs need any change?

No. `.readthedocs.yml` installs the project with the `docs` dependency group, which is where the extension is added, and `conf.py` is the configuration it builds from. The next build on the service includes the toggle.

### What if the extension does not support the installed theme version?

The run installs the extension against `sphinx-rtd-theme >=3.0.0` and builds with `-W` before pinning a lower bound. If the current release breaks the build, the pull request says which release built and pins that one, and the reviewer decides whether to wait for a fix.

### Will the PDF build change?

No. The extension adds JavaScript and CSS to the HTML builders only, and `.readthedocs.yml`'s `formats: [pdf]` goes through the LaTeX builder, which does not load them.

## More Sphinx jobs

- [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/)
- [Add i18n to a Sphinx Docs Site](https://getrush.ai/run/add-i18n/sphinx/)

## The same job on other stacks

- [Add Dark Mode to a SvelteKit App](https://getrush.ai/run/add-dark-mode/sveltekit/)
- [Add Dark Mode to a Symfony App](https://getrush.ai/run/add-dark-mode/symfony/)
- [Add Dark Mode to a Tauri App](https://getrush.ai/run/add-dark-mode/tauri/)

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