feat: add mermaid diagram rendering via sphinxcontrib.mermaid

[illilillillili]

Adds support for

```{mermaid}
block
  a
  b
```

or in rst

.. mermaid::

   %%{init: {'theme':'base'}}%%
   block
   a
   b

and renders it with mmdc (configurable) to svg, which is then imported as an image

conf.py could contain:

mermaid_cmd = "/path/to/mmdc" # or "mmdc" by default

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 28a57d1b-7356-4702-b663-f1a8ccf7511a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

TypstTranslator in src/atsphinx/typst/writer.py gains mermaid diagram support. "mermaid" is added to the optional node list. A new mermaid_render_to_svg() method normalizes mermaid_cmd to an absolute path, temporarily patches the builder's imagedir/imgpath, calls sphinxcontrib.mermaid.render_mm to produce SVG output, then restores original state. visit_mermaid() extracts node attributes, invokes mermaid_render_to_svg(), constructs a docutils.nodes.image pointing to the SVG, delegates to the base image visitor, and always raises SkipNode. Failures (including missing sphinxcontrib.mermaid) are caught and logged. depart_mermaid() is a no-op.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding Mermaid diagram rendering via sphinxcontrib.mermaid.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/atsphinx/typst/writer.py`:
- Around line 200-205: The Mermaid rendering fallback in writer.py uses a bare
except in the render_mm call path, which can swallow BaseException and violates
Ruff E722. Update the exception handling in the Mermaid render block inside the
writer logic to catch Exception or a narrower render-specific error instead,
while keeping the existing logger.exception and relfn/outfn fallback behavior
unchanged.
- Around line 239-244: The Mermaid rendering fallback in
TypstTranslator.visit_mermaid is swallowing Docutils SkipNode from the delegated
image rendering, which turns normal skip control flow into a false failure log.
Update the exception handling around the super(TypstTranslator,
self).visit_image and super(TypstTranslator, self).depart_image calls to
explicitly catch and re-raise nodes.SkipNode before the generic Exception
handler, while keeping the existing ImportError and warning behavior for real
failures.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 50e5421b-0494-475c-8faa-c2d2661263e7

📥 Commits

Reviewing files that changed from the base of the PR and between e11e2ba and 7c6b306.

📒 Files selected for processing (1)

• src/atsphinx/typst/writer.py