Merge pull request #137 from lsst-sqre/tickets/DM-36259

DM-36259: Include mermaid in the user guide extensions

docs/_rst_epilog.rst

@@ -9,6 +9,10 @@
 .. _SCons: https://scons.org
 .. _Sphinx extensions: https://www.sphinx-doc.org/en/master/develop.html
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
+.. _Mermaid: https://mermaid-js.github.io/mermaid/#/
+.. _sphinxcontrib-mermaid: https://github.com/mgaitan/sphinxcontrib-mermaid
+.. _Diagrams: https://diagrams.mingrammer.com/
+.. _sphinx-diagrams: https://github.com/j-martin/sphinx-diagrams
 .. _`#dm-docs`: https://lsstc.slack.com/archives/C2B6DQBAL
 .. _`DMTN-030`:
 .. _`DMTN-030 Science Pipelines Documentation Design`: https://dmtn-030.lsst.io
@@ -46,9 +50,11 @@
 .. _napoleon: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
 .. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
 .. _sphinx_autodoc_typehints: https://github.com/tox-dev/sphinx-autodoc-typehints
+.. _tox: https://tox.wiki/en/latest/
 
 .. Internal links
 
+.. |documenteer.toml| replace:: :doc:`documenteer.toml </guides/toml-reference>`
 .. |documenteer.conf.guide| replace:: :doc:`documenteer.conf.guide </guides/configuration-preset>`
 .. |package-docs| replace:: :doc:`package-docs </pipelines/package-docs-cli>`
 .. |stack-docs| replace:: :doc:`stack-docs </pipelines/stack-docs-cli>`

docs/documenteer.toml

@@ -34,3 +34,8 @@ requests = "https://requests.readthedocs.io/en/latest/"
 developer = "https://developer.lsst.io/"
 pybtex = "https://docs.pybtex.org/"
 sphinx = "https://www.sphinx-doc.org/en/master/"
+
+[sphinx.linkcheck]
+ignore = [
+    "https://mermaid-js.github.io"
+]

docs/guides/diagrams.rst

@@ -0,0 +1,154 @@
+################
+Diagrams as code
+################
+
+Rubin user guides use Mermaid_ (through sphinxcontrib-mermaid_) for diagrams-as-code.
+With Mermaid, you can express common diagram types like flow charts, sequence diagrams, and entity relationship diagrams with plain text source code.
+The diagrams on rendered dynamically, within the web client.
+Mermaid makes diagrams more maintainable since you don't need to manage proprietary graphics formats and binary files.
+
+Basic syntax
+============
+
+Embedded diagrams
+-----------------
+
+Diagrams can be embedded directly in the page's source with the ``mermaid`` directive:
+
+.. tab-set-code::
+
+   .. code-block:: rst
+
+     .. mermaid::
+
+        flowchart LR
+          rsp(Rubin Science Platform)
+          rsp --> p(Portal)
+          rsp --> n(Notebooks)
+          rsp --> a(APIs)
+          p --> a
+          n --> a
+
+   .. code-block:: md
+
+     ```mermaid
+     flowchart LR
+       rsp(Rubin Science Platform)
+       rsp --> p(Portal)
+       rsp --> n(Notebooks)
+       rsp --> a(APIs)
+       p --> a
+       n --> a
+     ```
+
+.. mermaid::
+
+    flowchart LR
+      rsp(Rubin Science Platform)
+      rsp --> p(Portal)
+      rsp --> n(Notebooks)
+      rsp --> a(APIs)
+      p --> a
+      n --> a
+
+Diagrams in separate files
+--------------------------
+
+You can create Mermaid_ diagrams in separate source files and reference them as arguments to the ``mermaid`` directive.
+
+.. tab-set-code::
+
+   .. code-block:: rst
+
+      .. mermaid:: diagram.mmd
+
+   .. code-block:: md
+
+      ```mermaid diagram.mmd
+      ```
+
+This approach is great for complex diagrams, especially since some editors provide syntax highlighting and live preview for Mermaid_ diagrams.
+
+Captions
+--------
+
+You can include a caption for the diagram with the ``caption`` option.
+
+.. tab-set-code::
+
+   .. code-block:: rst
+
+      .. mermaid:: diagram.mmd
+         :caption: My diagram.
+
+   .. code-block:: md
+
+      ```mermaid diagram.mmd
+      :caption: My diagram.
+      ```
+
+Mermaid diagram types
+=====================
+
+Mermaid_ supports many diagram types, including:
+
+- `Flowcharts <https://mermaid-js.github.io/mermaid/#/flowchart>`__
+- `Sequence diagrams <https://mermaid-js.github.io/mermaid/#/sequenceDiagram>`__
+- `Entity relationship diagrams <https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram>`__
+- `Gantt <https://mermaid-js.github.io/mermaid/#/gantt>`__
+
+See the Mermaid_ documentation for details on the available diagram types and their syntax.
+
+Diagrams for architectural diagrams
+===================================
+
+Mermaid_ does not have support for architectural diagrams (that is, diagrams showing the infrastructure and services in a deployment).
+For this application the Diagrams_ package, with the sphinx-diagrams_ extension, is ideal.
+
+Installation and set up
+-----------------------
+
+sphinx-diagrams_ is not part of the standard Documenteer configuration for Rubin user guides.
+You'll need to install and configure it:
+
+1. Add the ``sphinx-diagrams`` Python dependency to your project's development/documentation requirements.
+
+2. Ensure that ``graphviz`` is available in the build environment.
+   If you are using GitHub Actions with an Ubuntu runner, this can be done with an apt installation:
+
+   .. code-block:: yaml
+      :caption: .github/workflows/ci.yaml
+
+      - name: Install graphviz
+        run: |
+          sudo apt-get install -y graphviz
+
+   If you are using tox_, you may need to add ``graphviz`` to the documentation environment's ``allowlist_externals`` configuration.
+
+3. Add ``"sphinx_diagrams"`` to the extensions list in |documenteer.toml|:
+
+   .. code-block:: toml
+      :caption: documenteer.toml
+
+      [sphinx]
+      extensions = [
+        "sphinx_diagrams"
+      ]
+
+Basic syntax
+------------
+
+You add Diagrams_\ -based diagrams to your documentation with ``diagrams`` directives.
+As with Mermaid, you can write Diagrams_ code both within the ``diagrams`` directive, or set the name (or path) of a Python file as an argument to the ``diagrams`` diagram.
+Referencing a Python module is recommended to take advantage of syntax highlighting in your code editor.
+
+.. tab-set-code::
+
+   .. code-block:: rst
+
+      .. diagrams:: diagram.py
+
+   .. code-block:: md
+
+      ```diagrams diagram.py
+      ```

docs/guides/index.rst

@@ -32,6 +32,7 @@ Documenteer provides a configuration profile for creating branded user guides wi
    :caption: Design features
    :name: toc-guides-design
 
+   diagrams
    badges
    tabsets
 

docs/guides/overview.rst

@@ -33,6 +33,14 @@ Rubin user guides can be written in Markdown, in addition to reStructuredText, t
 Through MyST_, reStructuredText/Sphinx directives and roles are available as a layer on top of standard Markdown syntax.
 See the MyST_ documentation for more details on how to use reStructuredText features from Markdown.
 
+Diagrams as code
+================
+
+Support for Mermaid_ is built in, enabling you to add standard technical diagrams with restoring to graphics editors or binary files
+For infrastructure diagrams, we recommend using Diagrams_, which you can easily install and configure.
+
+See :doc:`diagrams` for more information.
+
 Python APIs with automodapi and autodoc
 =======================================
 

pyproject.toml

@@ -70,6 +70,7 @@ guide = [
     "sphinx-prompt",
     "myst-parser",
     "markdown-it-py[linkify]",
+    "sphinxcontrib-mermaid",
 ]
 technote = [
     # Theme and extensions for technotes

src/documenteer/conf/guide.py

@@ -29,7 +29,9 @@
 # #API
 #     API reference configuration
 # #MYST
-#     My-ST markdown configurations
+#     MyST markdown configurations
+# #MERMIAID
+#     Mermaid diagram support
 
 
 # Ordered as they are declared in this module
@@ -91,6 +93,8 @@
     "napoleon_attr_annotations",
     # MYST
     "myst_enable_extensions",
+    # MERMAID
+    "mermaid_output_format",
 ]
 
 _conf = DocumenteerConfig.find_and_load()
@@ -104,6 +108,7 @@
     "myst_parser",
     "sphinx_copybutton",
     "sphinx_design",
+    "sphinxcontrib.mermaid",
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
@@ -305,9 +310,8 @@
 napoleon_type_aliases = None
 napoleon_attr_annotations = True
 
-
 # ============================================================================
-# #MYST My-ST markdown configurations
+# #MYST MyST markdown configurations
 # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
 # ============================================================================
 
@@ -326,3 +330,13 @@
     "substitution",
     "tasklist",
 ]
+
+# ============================================================================
+# #MERMIAID Mermaid diagram support
+# https://github.com/mgaitan/sphinxcontrib-mermaid
+# https://mermaid-js.github.io/mermaid/#/
+# ============================================================================
+
+# The raw format renders the diagram client-side, and doesn't require a
+# Mermaid CLI installation
+mermaid_output_format = "raw"