docs: make the mermaid diagrams readable (#1103)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change. Narrow runs only, listed below.

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• release — bumps the version or rolls up a distribution
• chore — anything else

---

Description

Refs #1103 (rendered-docs proofread). The user saw tangled, unreadable Mermaid graphs on the docs site.

• Cause: the sphinxcontrib-mermaid defaults fit every SVG into a fixed 500px box. On the page the protocol hierarchy rendered at 0.14x and the field hierarchy at 0.19x, so text and edges ran together. conf.py now renders each diagram at its natural size, shrunk only to the page width; _static/mermaid.css centres narrow ones.
• Per graph: protocols, workflows (split into triggers and workflow-to-workflow chain), engines, releasing, registry-protocol and mint-criterion are reordered or restacked to remove crossings. No node is dropped and every edge condition is kept (registry-protocol merges parallel edges into one labelled edge). Mermaid reads labels as Markdown, so _missing_, _member_map_ and __version__ are escaped.
• Links: click targets were root-absolute and 404 under the site's /PyPCAPKit/ prefix. They are now page-relative, and every local target resolves to a 200 with its anchor present (headless Chrome, served under the prefix).
• Prose: workflows.rst now states which triggers run each gate-only call. The old "only on the Saturday schedule path" was wrong for Create Release, which runs on a v* tag push. documentation.rst gains the escape and click-target rules.

Rejected on measurement: ELK layout (wider, reorders siblings) and tighter spacing (only 10–15% narrower). Not fixed: a few edges still run under labels in the two workflows graphs (far fewer than before); no variant tried cleared the chain graph's without adding crossings.

Checks: clean -E builds of main and this head give the same warnings by (page, message). tests/project: 950 passed, 1 skipped. test_workflows_at_a_glance_1732.py also passes merged with #1817, which edits that test.

[JarryShaw]

Verdict: GOOD TO GO at 7b2c6fa77. A Sonnet cross-review (author: Opus) rebuilt the head and served it under /PyPCAPKit/. It then clicked every diagram link in headless Chrome: all land on a 200 or 304 with the anchor present, and the live site confirms the prefix. The rewritten trigger paragraph matches every on: block and gate if: on main. The added CSS only adds mermaid.css, and narrow diagrams are centred. The warning sets are identical and tests/project passes. Non-blocking, deferred to #1103's next round: "runs on both of its triggers" should say "can run", because version_check must pass; adding curve: monotoneX to the trigger graph would clear most of its remaining overlaps.