commit 389664e512b5964bf04e3bb0e977e20e2d4664fc
author Anthony DiGirolamo <tonymd@google.com> Thu May 06 16:57:20 2021 -0700
committer CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com> Fri May 07 15:57:23 2021 +0000
tree f09905235226761347e1e381882cd3c1f2614350
parent 3c78699ee74035046b1d3b37200908ee8a282410

pw_docgen: Add sphinxcontrib-mermaid

This allows for embedding mermaid diagrams in rst files. It uses
https://github.com/mgaitan/sphinxcontrib-mermaid

For example:

.. mermaid::

   sequenceDiagram
      participant Alice
      participant Bob
      Alice->John: Hello John, how are you?
      loop Healthcheck
          John->John: Fight against hypochondria
      end
      Note right of John: Rational thoughts <br/>prevail...
      John-->Alice: Great!
      John->Bob: How about you?
      Bob-->John: Jolly good!

Change-Id: I04ee218cfb6e3a6cfdd3f3e189a5a632d5628bee
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/44021
Reviewed-by: Rob Mohr <mohrr@google.com>
Commit-Queue: Anthony DiGirolamo <tonymd@google.com>

docs/conf.py

diff --git a/docs/conf.py b/docs/conf.py
index 3568fea..b7bbda8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -48,6 +48,7 @@
     'sphinxcontrib.actdiag',
     'sphinxcontrib.rackdiag',
     'sphinxcontrib.packetdiag',
+    'sphinxcontrib.mermaid',
 ]
 
 _DIAG_HTML_IMAGE_FORMAT = 'SVG'

pw_docgen/docs.rst

diff --git a/pw_docgen/docs.rst b/pw_docgen/docs.rst
index 041893e..fcb028e 100644
--- a/pw_docgen/docs.rst
+++ b/pw_docgen/docs.rst
@@ -38,6 +38,20 @@
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _Sphinx: http://www.sphinx-doc.org/en/master
 
+There are additonal Sphinx plugins used for rendering diagrams within
+reStructuredText files including:
+
+* `Blockdiag <http://blockdiag.com/>`_ via these sphinxcontrib packages:
+
+    * `sphinxcontrib-blockdiag
+      <https://pypi.org/project/sphinxcontrib-blockdiag/>`_
+    * `sphinxcontrib-actdiag <https://pypi.org/project/sphinxcontrib-actdiag/>`_
+    * `sphinxcontrib-nwdiag <https://pypi.org/project/sphinxcontrib-nwdiag/>`_
+    * `sphinxcontrib-seqdiag <https://pypi.org/project/sphinxcontrib-seqdiag/>`_
+
+* `mermaid <https://mermaid-js.github.io/>`_ via the `sphinxcontrib-mermaid
+  <https://pypi.org/project/sphinxcontrib-mermaid/>`_ package.
+
 Documentation source and asset files are placed alongside code within a module
 and registered as a ``pw_docgen_group`` target within a ``BUILD.gn`` file. These
 groups become available for import within a special documentation generation

pw_docgen/py/setup.py

diff --git a/pw_docgen/py/setup.py b/pw_docgen/py/setup.py
index 45d273a..a49efba 100644
--- a/pw_docgen/py/setup.py
+++ b/pw_docgen/py/setup.py
@@ -33,5 +33,6 @@
         'sphinxcontrib-blockdiag',
         'sphinxcontrib-nwdiag',
         'sphinxcontrib-seqdiag',
+        'sphinxcontrib-mermaid',
     ],
 )