doc: Support rendering of Mermaid.js diagrams, à la Graphviz diagrams

Mermaid.js¹ supports a number of useful diagrams types that are
otherwise difficult to create programmatically.  The addition now is
motivated by wanting to add some sequence diagrams for new authn
documentation.

The Sphinx/Mermaid integration, sphinxcontrib-mermaid, defaults to
client-side rendering at page load time, but this comes with some
downsides and practically no upsides.  Configure it to render at doc
build time instead.

Related to this change, I submitted two patches upstream to the Sphinx
integration which I think improve the build-time render results: a patch
to remove unnecessary JS from the page by default² and a patch to
display the SVGs as images rather than embedded documents.³

¹ <https://mermaid.js.org>
² <mgaitan/sphinxcontrib-mermaid#132>
³ <mgaitan/sphinxcontrib-mermaid#131>

.readthedocs.yml

@@ -4,6 +4,7 @@ build:
   os: ubuntu-20.04
   tools:
     python: "3.10"
+    nodejs: "16"
 sphinx:
   builder: dirhtml
 python:

devel/mmdc

@@ -0,0 +1,2 @@
+#!/bin/bash
+exec npx --package @mermaid-js/mermaid-cli -- mmdc "$@"

doc/conf.py

@@ -4,6 +4,8 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+from pathlib import Path
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -38,6 +40,7 @@
     'sphinx.ext.intersphinx',
     'sphinx_markdown_tables',
     'nextstrain.sphinx.theme',
+    'sphinxcontrib.mermaid',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -72,3 +75,24 @@
     'docs': ('https://docs.nextstrain.org/en/latest/', None),
 }
 
+# -- Mermaid -----------------------------------------------------------------
+
+# Render Mermaid.js diagrams to SVG at Sphinx build time (like Graphviz
+# diagrams are) so that they don't have to render via JS at page load time.
+# Various upsides to this, but one is that you can pass around the SVGs as
+# images.
+mermaid_output_format = 'svg'
+
+# Use a command wrapper which automatically provisions the Mermaid CLI (mmdc)
+# via npx so it doesn't need to be installed on Read the Docs or by developers.
+mermaid_cmd = str(Path(__file__).resolve().parent.parent / "devel/mmdc")
+
+# Disable loading the JS library in doc pages.
+#
+# XXX TODO: Remove this once/if my patch to make it unnecessary¹ is accepted
+# and released.
+#   -trs, 9 Nov 2023
+#
+# ¹ <https://github.com/mgaitan/sphinxcontrib-mermaid/pull/132>
+mermaid_version = ""
+mermaid_init_js = ""

setup.py

@@ -131,6 +131,7 @@ def find_namespaced_packages(namespace):
     extras_require = {
         "dev": [
             "flake8 >=4.0.0",
+            "sphinxcontrib-mermaid",
             "mypy <1.6",
             "nextstrain-sphinx-theme>=2022.5",
             "pytest; python_version != '3.9'",