Use myst-parser mapping of fences as directives to have interoperable

rendering between Sphinx and GitHub. Refs: mgaitan/sphinxcontrib-mermaid#108 mgaitan/sphinxcontrib-mermaid#99
kdeldycke · Mar 28, 2023 · b972cf5 · b972cf5
1 parent 2a3e09b
commit b972cf5
Show file tree

Hide file tree

Showing 6 changed files with 19 additions and 18 deletions.
diff --git a/click_extra/docs_update.py b/click_extra/docs_update.py
@@ -136,16 +136,13 @@ def generate_platforms_graph(
     # Wrap the Mermaid code into a MyST block.
     return "\n".join(
         (
-            "```{mermaid}",
-            # XXX Titles are not supported by sphinxcontrib-mermaid yet:
-            # https://github.com/mgaitan/sphinxcontrib-mermaid/issues/108
-            #
-            # "---",
-            # (
-            #     f"title: click_extra.platforms.{graph_id} - {description}"
-            #     f" (Click Extra v{__version__})"
-            # ),
-            # "---",
+            # Use attributes blocks extension to add a title.
+            (
+                '{caption="'
+                f"`click_extra.platforms.{graph_id}` - {description}"
+                '"}'
+            ),
+            "```mermaid",
             "flowchart",
             indent("\n".join(sorted(subgraphs)), INDENT),
             "```",

diff --git a/docs/conf.py b/docs/conf.py
@@ -44,8 +44,10 @@
 ]
 
 myst_enable_extensions = [
+    "attrs_block",
     "colon_fence",
 ]
+myst_fence_as_directive = ["mermaid"]
 
 master_doc = "index"
 

diff --git a/docs/install.md b/docs/install.md
@@ -21,4 +21,4 @@ FYI, here is a graph of Python package dependencies:
 ```{eval-rst}
 .. mermaid:: images/dependencies.mmd
    :align: center
-```
+```
diff --git a/docs/platforms.md b/docs/platforms.md
@@ -6,7 +6,8 @@ All platforms are grouped in sets of non-overlaping families:
 
 <!-- NON_OVERLAPPING_GROUPS-graph-start -->
 
-```{mermaid}
+{caption="`click_extra.platforms.NON_OVERLAPPING_GROUPS` - Non-overlapping groups."}
+```mermaid
 flowchart
     subgraph <code>click_extra.platforms.ALL_LINUX</code><br/><em>All Linux</em>
         all_linux_linux(<code>linux</code><br/><em>Linux</em>)
@@ -45,7 +46,8 @@ Other groups are available for convenience, but these overlaps:
 
 <!-- EXTRA_GROUPS-graph-start -->
 
-```{mermaid}
+{caption="`click_extra.platforms.EXTRA_GROUPS` - Overlapping groups, defined for convenience."}
+```mermaid
 flowchart
     subgraph <code>click_extra.platforms.ALL_PLATFORMS</code><br/><em>All platforms</em>
         all_platforms_aix(<code>aix</code><br/><em>AIX</em>)

diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -96,7 +96,7 @@ xmltodict = ">=0.12,<0.14"
 bump2version = "^1.0.1"
 coverage = { extras = ["toml"], version = "^7.2" }
 mypy = "^1.1"
-myst-parser = "^0.19.1"
+myst-parser = "^1.0.0"
 pytest = "^7.2.2"
 # More pytest plugins at: https://docs.pytest.org/en/latest/reference/plugin_list.html
 pytest-cases = "^3.6.14"