# Add Mermaid Diagrams to Sphinx Docs

Yes. An agent adds sphinxcontrib-mermaid to a MyST Sphinx site, draws the flows the prose describes, builds with -W so nothing warns, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-mermaid-diagrams/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 documentation is built before it touches a page. In a project laid out like pallets/click, every page under `docs/` is Markdown parsed by `myst_parser`, and `docs/conf.py` lists `sphinx.ext.autodoc`, `sphinx.ext.extlinks`, `sphinx.ext.intersphinx`, `sphinx_tabs.tabs`, `sphinxcontrib.log_cabinet`, `pallets_sphinx_themes` and `myst_parser` in `extensions`, with `myst_enable_extensions = ["attrs_block"]`, `myst_heading_anchors = 3` and `html_theme = "click"`. The docs dependencies are a `docs` group in `pyproject.toml` (`myst-parser`, `pallets-sphinx-themes`, `sphinx`, `sphinx-tabs`, `sphinxcontrib-log-cabinet`) resolved in `uv.lock`; `[tool.tox.env.docs]` runs `sphinx-build -E -W -b dirhtml docs docs/_build/dirhtml`, and `.readthedocs.yaml` installs uv through asdf on Python 3.13 and runs `uv run --group docs sphinx-build -W -b dirhtml docs $READTHEDOCS_OUTPUT/html`. That `-W` matters: any warning fails the build. `.pre-commit-config.yaml` runs ruff, codespell and the `uv-lock` hook, and `tests.yaml` ignores `docs/**`, so the docs build is the only check that sees these changes. `docs/_static` holds three SVG logos and no page has a diagram; the pages that describe structure in words, `complex.md` under "Contexts", `click-concepts.md` under "Callback Evaluation Order" and `commands-and-groups.md` under "Arbitrary Nesting", are where one belongs.

The dependency goes in with `uv add --group docs sphinxcontrib-mermaid`, which updates `pyproject.toml` and `uv.lock` together so the `uv-lock` hook stays green, and `"sphinxcontrib.mermaid"` is appended to `extensions`. The agent sets `myst_fence_as_directive = ["mermaid"]` so a plain fenced block with `mermaid` as its info string is treated as the directive; the same source then renders on GitHub's file view, which supports the fence, and in Sphinx. It leaves `mermaid_output_format` at its default, `raw`: the HTML builder writes a `div` with `class="mermaid"` and loads mermaid.js, at the version in `mermaid_version`, from jsdelivr when the page is viewed, so the Read the Docs build needs no Node, no `mmdc` and no browser. The option to render SVG or PNG at build time through `mermaid_cmd` is named in the pull request as the alternative for an offline or PDF build.

Three diagrams are drawn from the code, not from the prose alone. For "Contexts" the agent reads `src/click/core.py`, where each `Context` keeps a `parent` and `command`, and draws the git-clone example from `complex.md` as a tree: the `cli` group's context at the top, the `clone` and `commit` contexts beneath it, and `ctx.obj` carried from the root. For "Callback Evaluation Order" it draws the flowchart the section spells out: eager parameters first, in the order the user typed them; the remaining parameters next, in that same order; missing parameters last, with their defaults. For "Arbitrary Nesting" it draws the group tree from the section's own example. Each block gets a `:caption:` and `:align: center`, sits directly under the sentence it illustrates, and uses only node labels that appear in the surrounding text so codespell has nothing new to learn.

The agent builds with `uv run --group docs sphinx-build -E -W -b dirhtml docs docs/_build/dirhtml`, the tox `docs` command, and confirms a clean exit, then opens the built `complex/index.html` in the sandbox's browser to see the three diagrams rendered by the loaded script, and keeps a screenshot. It runs `pre-commit run --all-files` so the lock hook, ruff and codespell pass over the edited files. Only then does it open the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Mermaid diagrams to this Sphinx documentation and open a pull request. Read docs/conf.py, pyproject.toml, uv.lock, .readthedocs.yaml, .pre-commit-config.yaml and every page under docs/ first, and read the source modules the pages describe. Add sphinxcontrib-mermaid to the docs dependency group with uv add --group docs so uv.lock is updated, append sphinxcontrib.mermaid to extensions, and set myst_fence_as_directive to [\"mermaid\"]. Keep the default raw output format. Add a diagram to each page that describes a structure or an order in prose: the context tree in the complex applications page, the callback evaluation order in the concepts page and the nested groups example, each with a caption and centred, each checked against the code it describes. Build with sphinx-build -E -W -b dirhtml and fix every warning, open the built page in the browser to confirm the diagrams render, run pre-commit run --all-files, then open a pull request that shows each diagram's source and the build 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 changes `pyproject.toml`, `uv.lock`, `docs/conf.py` and the three pages that gained a diagram. Its description shows the source of each diagram beside the sentence it illustrates, quotes the `sphinx-build -W` output ending without a warning, and attaches the screenshot of the rendered page from the sandbox's browser so a reviewer need not build the docs to see the result.

It states plainly that the pages now load a script from a CDN at view time, names `mermaid_version` as the pin and `mermaid_use_local` as the way to serve a local copy instead, and lists the SVG and PNG output formats as the route to a diagram that works in a PDF build.

Before merging, a reviewer checks each diagram against the code rather than the prose: that the context tree matches how `Context.parent` is set, that the evaluation order shows eager parameters before the rest, and that no node label contradicts a term the page defines. They also decide whether a CDN script is acceptable for the documentation site.

## Run it on every new documentation page

An automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request adds or rewrites a page under docs/ that explains an order of operations or a tree of objects, draw it as a Mermaid block under the relevant paragraph, build with -W, and push to the pull request's branch" starts one run per opened pull request. The trigger adds the pull request after the prompt and fills in nothing else, so a pull request that only fixes a typo gets a run that reads the diff and stops.

A maintainer of several Sphinx projects sends this body once per repository from their own server, each `POST /o/{org}/sessions` with that 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. A project whose docs are reStructuredText gets `.. mermaid::` directives instead of fenced blocks, and one that pins docs requirements in a `requirements.txt` gets the package pinned there rather than in a uv group.

## Why run it on Rush?

A diagram is only worth adding if it is right, and being right means reading the code behind the prose: how a `Context` links to its parent, which parameters are eager, how a group holds its commands. The agent reads those modules, draws from them, and proves the result the way the project proves its docs, with `sphinx-build -W` in a sandbox that has the same uv-managed environment Read the Docs uses and a browser to see the rendered page.

The build log, the pre-commit run and the screenshot stay with the run, so the reviewer's job is to judge the diagrams, not to reproduce the build. A team with many Sphinx sites sends one request per repository and reads one pull request per site, each with its own proof.

## Frequently asked questions

### Does Read the Docs need Node or mermaid-cli for this?

No. With `mermaid_output_format` at its default `raw`, Sphinx emits the diagram source in a `div` with `class="mermaid"` and the page loads mermaid.js from jsdelivr in the reader's browser. `mmdc`, and the Node runtime it needs, only matter if the format is switched to `svg` or `png`.

### Will the diagrams survive the `-W` build?

Yes, and that is checked in the run. The extension registers the `mermaid` directive, and `myst_fence_as_directive` maps the fence to it, so there is no unknown-directive warning. The agent builds with `-E -W` exactly as the tox `docs` environment does and fixes any warning before opening the pull request.

### Can the diagrams be served without a CDN?

Yes. `mermaid_use_local` points the extension at a local copy of mermaid.js placed under `docs/_static`, which `html_static_path` already includes. The pull request names the option; switching to it is one line in `docs/conf.py` plus the file.

### Does this touch the `click:example` and `click:run` blocks?

No. Those come from `pallets_sphinx_themes` inside `{eval-rst}` blocks and keep rendering runnable examples as before. The diagrams are separate fenced blocks placed under the prose, and no existing block is edited.

## More Sphinx jobs

- [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/)
- [Add Redirects for Moved Pages to Sphinx Docs](https://getrush.ai/run/add-redirects/sphinx/)

## The same job on other stacks

- [Add Mermaid Diagrams to a Starlight Docs Site](https://getrush.ai/run/add-mermaid-diagrams/starlight/)
- [Add Mermaid Diagrams to a VitePress Site](https://getrush.ai/run/add-mermaid-diagrams/vitepress/)
- [Add Mermaid Diagrams to a Docusaurus Site](https://getrush.ai/run/add-mermaid-diagrams/docusaurus/)

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