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 with this body:
{
"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"
}
]
}- 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 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add Dark Mode to a SvelteKit App (SvelteKit)
- Add Dark Mode to a Symfony App (Symfony)
- Add Dark Mode to a Tauri App (Tauri)