From b422de4f91441e960746f069a0ba5beb2a9011a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Ag=C3=BCero?= Date: Fri, 21 Aug 2026 18:07:25 +0200 Subject: [PATCH] Add mermaid diagram support to sphinx-honu (0.2.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Assisted-by: Claude Fable 5 Signed-off-by: Carlos Agüero --- .github/workflows/docs.yml | 2 +- docs/requirements.txt | 2 +- docs/usage.md | 7 ++++--- pyproject.toml | 3 ++- sphinx_honu/__init__.py | 7 +++++-- tests/fixture/docs/usage.md | 5 +++++ tests/test_build.py | 6 ++++++ 7 files changed, 24 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 7ccd12e..d0a11b4 100644 --- a/.github/workflows/docs.yml +++ b/.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: diff --git a/docs/requirements.txt b/docs/requirements.txt index 98438b8..962dd5d 100644 --- a/docs/requirements.txt +++ b/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 . diff --git a/docs/usage.md b/docs/usage.md index de1eecf..128266d 100644 --- a/docs/usage.md +++ b/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//`. 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 diff --git a/pyproject.toml b/pyproject.toml index becc1cf..d5c32c5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ 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" @@ -12,6 +12,7 @@ dependencies = [ "sphinx>=7", "sphinx-rtd-theme>=2", "myst-parser>=2", + "sphinxcontrib-mermaid>=0.9", ] [project.scripts] diff --git a/sphinx_honu/__init__.py b/sphinx_honu/__init__.py index 7017a81..7834403 100644 --- a/sphinx_honu/__init__.py +++ b/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) diff --git a/tests/fixture/docs/usage.md b/tests/fixture/docs/usage.md index dd0edea..b5c20bf 100644 --- a/tests/fixture/docs/usage.md +++ b/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] +``` diff --git a/tests/test_build.py b/tests/test_build.py index b18d5d7..5ebc6ce 100644 --- a/tests/test_build.py +++ b/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': ''})