Add mermaid diagram support to sphinx-honu (0.2.0)

.github/workflows/docs.yml

@@ -4,7 +4,7 @@
 #
 #   jobs:
 #     docs:
-#       uses: HonuRobotics/honu-docs/.github/workflows/docs.yml@v0.1.0
+#       uses: HonuRobotics/honu-docs/.github/workflows/docs.yml@v0.2.0
 #       permissions:
 #         contents: write
 #       with:

docs/requirements.txt

@@ -1,4 +1,4 @@
 # This repository dogfoods its own package from the working tree. Consumer
 # repositories pin a release tag instead:
-#   sphinx-honu @ git+https://github.com/HonuRobotics/honu-docs@v0.1.0
+#   sphinx-honu @ git+https://github.com/HonuRobotics/honu-docs@v0.2.0
 .

docs/usage.md

@@ -21,7 +21,7 @@ extension defaults.
 ## 2. `docs/requirements.txt`
 
 ```text
-sphinx-honu @ git+https://github.com/HonuRobotics/honu-docs@v0.1.0
+sphinx-honu @ git+https://github.com/HonuRobotics/honu-docs@v0.2.0
 ```
 
 Pin a release tag. Rebuilding an old distribution branch keeps the exact
@@ -39,7 +39,7 @@ on:
 
 jobs:
   docs:
-    uses: HonuRobotics/honu-docs/.github/workflows/docs.yml@v0.1.0
+    uses: HonuRobotics/honu-docs/.github/workflows/docs.yml@v0.2.0
     permissions:
       contents: write
     with:
@@ -63,7 +63,8 @@ The site appears at `https://honurobotics.github.io/<repository>/`.
 
 Pages are MyST Markdown. Hidden `toctree` blocks in section index pages
 build the sidebar; the `colon_fence` extension is enabled so admonitions
-can be written with `:::` fences. Build locally with:
+can be written with `:::` fences, and diagrams are text in
+```` ```{mermaid} ```` blocks (rendered in the browser). Build locally with:
 
 ```bash
 pip install -r docs/requirements.txt

pyproject.toml

@@ -4,14 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sphinx-honu"
-version = "0.1.0"
+version = "0.2.0"
 description = "Honu Robotics documentation house style: docs.ros.org functionality, Honu branding"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
   "sphinx>=7",
   "sphinx-rtd-theme>=2",
   "myst-parser>=2",
+  "sphinxcontrib-mermaid>=0.9",
 ]
 
 [project.scripts]

sphinx_honu/__init__.py

@@ -4,7 +4,7 @@
 extension applies the stock sphinx_rtd_theme configured exactly as
 docs.ros.org (ros2/ros2_documentation) runs it, adds the Honu brand skin,
 the version flyout and the GitHub edit link, and wires MyST so pages are
-written in Markdown.
+written in Markdown, with mermaid for diagrams.
 
 Only settings the consumer left untouched are filled in, so any value set
 explicitly in a consumer conf.py wins.
@@ -20,7 +20,7 @@
 import os
 from pathlib import Path
 
-__version__ = '0.1.0'
+__version__ = '0.2.0'
 
 _HERE = Path(__file__).resolve().parent
 
@@ -86,6 +86,9 @@ def _config_inited(app, config):
 
 def setup(app):
     app.setup_extension('myst_parser')
+    # Diagrams as text: ```{mermaid} blocks render client side, so pages
+    # stay editable and the build needs no graphviz.
+    app.setup_extension('sphinxcontrib.mermaid')
     app.add_config_value('honu_github', None, 'html')
     app.add_config_value('honu_docs_dir', 'docs', 'html')
     app.connect('config-inited', _config_inited)

tests/fixture/docs/usage.md

@@ -2,3 +2,8 @@
 
 A second page so the sidebar, the toctree and the GitHub edit link have
 something to render.
+
+```{mermaid}
+graph LR
+  A[config] --> B[URDF]
+```

tests/test_build.py

@@ -65,6 +65,12 @@ def test_myst_note_rendered(site):
     assert 'admonition note' in index, 'colon fence admonition not rendered'
 
 
+def test_mermaid_diagrams_render(site):
+    usage = (site / 'usage.html').read_text()
+    assert 'mermaid' in usage, 'mermaid block did not reach the page'
+    assert 'graph LR' in usage
+
+
 def test_local_build_defaults(tmp_path):
     out = build(tmp_path, {'DOCS_VERSION': '', 'DOCS_BASEURL': '',
                            'DOCS_VERSIONS': ''})