Docs: consume sphinx-gp-mermaid, drop the vendored renderer by tony · Pull Request #1073 · tmux-python/tmuxp · GitHub

Summary

Replace the vendored docs/_ext/mermaid_inline.py with sphinx-gp-mermaid, the gp-sphinx workspace package it was extracted into — the same build-time dual light/dark inline-SVG pipeline introduced in Docs: build-time mermaid + tmux-layout diagram rendering #1071, now maintained upstream.
Add the package to the dev and docs dependency groups, pinned to sphinx-gp-mermaid==0.0.1a32 from PyPI alongside the other gp-sphinx-family packages.
Remove the vendored extension, its stylesheet, and its test suite — the code and its tests now live in the gp-sphinx workspace.
Zero re-render migration: the package kept the cache-key inputs identical, so every existing docs/_mermaid_cache SVG remains a cache hit; adoption never launches Chrome.

Changes

pyproject.toml / uv.lock: the dependency and its exclude-newer-cooldown exemption alongside the other gp-sphinx-family packages.
docs/conf.py: extra_extensions loads sphinx_gp_mermaid. The explicit myst_fence_as_directive=["mermaid"] stays for now — the pinned gp-sphinx release predates the upstream auto-routing — and drops on the next gp-sphinx bump.
docs/AGENTS.md, .gitignore, .github/workflows/docs.yml: authoring guidance and comments retargeted at the package. The pnpm/puppeteer provisioning is unchanged: mermaid-cli remains a docs devDependency here, since the Python package resolves mmdc but does not vendor it.

Rendered markup now uses the package's workspace-namespaced CSS classes (gp-sphinx-diagram* in place of gp-diagram*), shipped by the package itself; visual output is unchanged.

Dependency status

sphinx-gp-mermaid==0.0.1a32 is a normal PyPI pin (the gp-sphinx release shipped — companion PR below), so the lockfile is reproducible and this PR is mergeable as-is.

Verification

Zero references to the vendored renderer or its CSS namespace remain:

rg -l 'mermaid_inline|gp-diagram'

Test plan

uv run ruff check ., uv run ruff format ., uv run mypy . — clean
uv run py.test --reruns 0 — suite green (the vendored mermaid tests moved upstream with the code)
just build-docs — every diagram page renders through the package; _mermaid_cache entries hit with no mmdc invocations (mtimes unchanged)
Built pages carry gp-sphinx-diagram__variant--theme-{light,dark} figures and link the packaged stylesheet

Companion PR

sphinx-gp-mermaid: build-time Mermaid diagrams as dual inline SVG git-pull/gp-sphinx#61 — the extracted sphinx-gp-mermaid package

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.56%. Comparing base (8d73d5e) to head (5aa5e90).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1073   +/-   ##
=======================================
  Coverage   82.56%   82.56%           
=======================================
  Files          31       31           
  Lines        2770     2770           
  Branches      518      518           
=======================================
  Hits         2287     2287           
  Misses        346      346           
  Partials      137      137

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

why: Verify the sphinx-gp-mermaid renderer on the live site — the production path runs behind Cloudflare (Rocket Loader), which local builds cannot reproduce. what: - Add mermaid to the docs workflow's push trigger - Force PUBLISH on the mermaid ref so a workflow-only push deploys Revert this commit before merging #1073.

Adds `sphinx-gp-mermaid`, a workspace package that renders MyST `mermaid` fences to inline SVG at build time via mermaid-cli. Diagrams paint with the page — no client-side runtime, no async pop-in, no layout shift — and follow the site's light/dark theme with no JavaScript. Extracted from tmuxp's production `docs/_ext/mermaid_inline.py`; tmuxp adopts the package in the companion PR. - **Dual-theme, zero-JS**: each diagram renders to a light and a dark SVG matched to the gp-furo palette, inlined and toggled by CSS on the page theme. Mermaid bakes id-scoped `!important` colors into its output, so a single render cannot follow the toggle. - **Content-addressed cache**: rendered SVGs are cached under `<confdir>/_mermaid_cache`, keyed on render version, theme, config, and source; the cache survives clean builds and writes atomically so parallel writers never read a torn SVG. - **Graceful degradation**: a missing or failing renderer warns once per builder and falls back to the diagram source, keeping `:name:` anchors intact; non-HTML builders emit an alt-text stand-in instead of crashing. - **Conf-level fence routing**: `merge_sphinx_config()` routes plain ```mermaid fences to the directive when the extension is active; explicit overrides still win. - **Opt-in**: not in `DEFAULT_EXTENSIONS` — rendering needs a Node toolchain (mermaid-cli + headless Chrome), so consumers who don't use diagrams pay nothing. - **Documentation**: ships the package's full Diátaxis tree (how-to, reference, dependents) and a live example gallery showing diverse diagram types as the extension's real dual-theme output. See also: tmux-python/tmuxp#1073

why: Verify the sphinx-gp-mermaid renderer on the live site — the production path runs behind Cloudflare (Rocket Loader), which local builds cannot reproduce. what: - Add mermaid to the docs workflow's push trigger - Force PUBLISH on the mermaid ref so a workflow-only push deploys Revert this commit before merging #1073.

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

why: The vendored mermaid renderer moved into the sphinx-gp-mermaid workspace package; the docs build needs it available before the local copy can be dropped. what: - Add sphinx-gp-mermaid==0.0.1a32 to the dev and docs groups - Bump the gp-sphinx family of packages to 0.0.1a32 - Regenerate uv.lock

why: The vendored docs/_ext/mermaid_inline.py moved into the sphinx-gp-mermaid workspace package; load the package instead so the local copy can be dropped. what: - extra_extensions: mermaid_inline -> sphinx_gp_mermaid - Keep the explicit myst_fence_as_directive: the pinned gp-sphinx release predates the auto-routing that ships with the package; drop it on the next gp-sphinx bump - Existing _mermaid_cache entries stay valid (identical cache-key inputs), so adoption re-renders nothing

why: The renderer now ships as sphinx-gp-mermaid and the docs build already loads the package, so the docs/_ext copy, its stylesheet, and its test suite are dead weight. what: - Delete docs/_ext/mermaid_inline.py, docs/_static/css/gp-diagram.css, and tests/test_docs_mermaid.py (the suite moved to the gp-sphinx workspace with the code) - Retarget the AGENTS.md diagrams convention, .gitignore comment, and docs.yml toolchain comment at the package; the pnpm/puppeteer provisioning itself is unchanged

why: Record for 1.74.0 that the docs mermaid renderer moved from a vendored extension to the reusable upstream sphinx-gp-mermaid package, with rendered output unchanged. what: - Add a Development entry under the unreleased 1.74.0 section

tony mentioned this pull request Jul 2, 2026

sphinx-gp-mermaid: build-time Mermaid diagrams as dual inline SVG git-pull/gp-sphinx#61

Merged

9 tasks

tony temporarily deployed to docs July 2, 2026 00:51 — with GitHub Actions Inactive

tony force-pushed the mermaid branch from d617d1d to 533e6a5 Compare July 2, 2026 00:55

tony temporarily deployed to docs July 2, 2026 00:55 — with GitHub Actions Inactive

tony force-pushed the mermaid branch from 533e6a5 to 2d3190a Compare July 4, 2026 11:05

tony temporarily deployed to docs July 4, 2026 11:05 — with GitHub Actions Inactive

tony force-pushed the mermaid branch from 2d3190a to fa579d7 Compare July 4, 2026 12:08

tony temporarily deployed to docs July 4, 2026 12:08 — with GitHub Actions Inactive

tony force-pushed the mermaid branch from fa579d7 to eec69ea Compare July 4, 2026 12:10

tony temporarily deployed to docs July 4, 2026 12:10 — with GitHub Actions Inactive

tony force-pushed the mermaid branch from eec69ea to f7b2b75 Compare July 4, 2026 12:20

tony added 3 commits July 4, 2026 07:34

tony force-pushed the mermaid branch from f7b2b75 to 2c89516 Compare July 4, 2026 12:35

docs(CHANGES): sphinx-gp-mermaid docs renderer

5aa5e90

why: Record for 1.74.0 that the docs mermaid renderer moved from a vendored extension to the reusable upstream sphinx-gp-mermaid package, with rendered output unchanged. what: - Add a Development entry under the unreleased 1.74.0 section

tony merged commit bca5998 into master Jul 4, 2026
14 checks passed

Docs: consume sphinx-gp-mermaid, drop the vendored renderer by tony · Pull Request #1073 · tmux-python/tmuxp · GitHub

Uh oh!

Docs: consume sphinx-gp-mermaid, drop the vendored renderer - #1073

Docs: consume sphinx-gp-mermaid, drop the vendored renderer#1073
tony merged 4 commits into
masterfrom
mermaid

tony commented Jul 2, 2026 •
edited
Loading

Uh oh!

Uh oh!

codecov Bot commented Jul 2, 2026 •
edited
Loading

Uh oh!

Uh oh!

tony commented Jul 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Docs: consume sphinx-gp-mermaid, drop the vendored renderer by tony · Pull Request #1073 · tmux-python/tmuxp · GitHub

Uh oh!

Docs: consume sphinx-gp-mermaid, drop the vendored renderer - #1073

Docs: consume sphinx-gp-mermaid, drop the vendored renderer#1073tony merged 4 commits intomastertmux-python/tmuxp:masterfrom mermaidtmux-python/tmuxp:mermaidCopy head branch name to clipboard

Conversation

tony commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Dependency status

Verification

Test plan

Companion PR

Uh oh!

codecov Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

tony commented Jul 4, 2026

Code review

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Docs: consume sphinx-gp-mermaid, drop the vendored renderer#1073
tony merged 4 commits into
masterfrom
mermaid

tony commented Jul 2, 2026 •
edited
Loading

codecov Bot commented Jul 2, 2026 •
edited
Loading