All jobs

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 RushOpens 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 with this body:

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading