docs: add mermaid extension

Author: lepture

docs/conf.py

@@ -27,12 +27,15 @@
     "nbsphinx",
     "numpydoc",
     "sphinx_sitemap",
+    "sphinxcontrib.mermaid",
 ]
 todo_include_todos = True
 autosummary_generate = True
 jupyter_sphinx_thebelab_config = {
     'requestKernel': True,
 }
+jupyter_sphinx_require_url = ''
+nbsphinx_requirejs_path = ''
 
 extlinks = {
     'pull': ('https://github.com/lepture/shibuya/pull/%s', 'pull request #%s'),

docs/contributing/roadmap.rst

@@ -23,7 +23,7 @@ These good things will be added in the future:
 - :bdg-success:`DONE` Perfect code highlight style
 - :bdg-success:`DONE` Edit this page link
 - :bdg-success:`DONE` GitHub stars and forks
-- :bdg-warning:`TODO` Scroll to top
+- :bdg-success:`DONE` Back to top
 - :bdg-success:`DONE` Breadcrumbs
 
 Design for other extensions
@@ -39,6 +39,7 @@ Make sure it works well with other extensions. Currently integrated with:
 - :bdg-success:`DONE` :ref:`nbsphinx`
 - :bdg-success:`DONE` :ref:`numpydoc`
 - :bdg-success:`DONE` ``sphinx-gallery``
+- :bdg-success:`DONE` :ref:`sphinxcontrib-mermaid`
 
 Instant search
 --------------

docs/extensions/mermaid.rst

@@ -0,0 +1,88 @@
+:description: Embed Mermaid flowcharts, sequence diagrams, gantt diagrams and more in your documents with Shibuya theme.
+
+.. _sphinxcontrib-mermaid:
+
+sphinxcontrib-mermaid
+=====================
+
+This extension allows you to embed Mermaid graphs in your documents,
+including general flowcharts, sequence diagrams, gantt diagrams and more.
+
+**Documentation**: https://sphinxcontrib-mermaid-demo.readthedocs.io/
+
+Install
+-------
+
+.. code-block:: bash
+
+    pip install sphinxcontrib-mermaid
+
+Then, add the extension to your ``conf.py``:
+
+.. code-block:: python
+    :caption: conf.py
+
+    extensions = [
+        # ...
+        "sphinxcontrib.mermaid",
+    ]
+
+Usage
+-----
+
+It adds a ``mermaid`` directive to embed mermaid markup. For example:
+
+.. code-block:: none
+
+    .. 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!
+
+.. 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!
+
+Mermaid not working
+-------------------
+
+You may encounter an error of::
+
+    Uncaught ReferenceError: mermaid is not defined
+
+Here are some possible fixes:
+
+1. There will be a ``requirejs`` conflict with :ref:`nbsphinx` extension,
+   you can use ``nbsphinx_requirejs_path`` setting to resolve the issue:
+
+   .. code-block:: python
+      :caption: conf.py
+
+      nbsphinx_requirejs_path = ''
+
+2. Mermaid extension is conflict with :ref:`sphinx-jupyter` too, you can
+   resolve the issue with ``jupyter_sphinx_require_url`` setting:
+
+   .. code-block:: python
+      :caption: conf.py
+
+      jupyter_sphinx_require_url = ''

docs/index.rst

@@ -74,6 +74,7 @@ Shibuya
     extensions/jupyter-sphinx
     extensions/nbsphinx
     extensions/numpydoc
+    extensions/mermaid
 
 .. toctree::
     :caption: Development

requirements.txt

@@ -5,6 +5,7 @@ sphinx-design
 ipykernel
 jupyter-sphinx
 sphinx-togglebutton
+sphinxcontrib-mermaid
 nbsphinx
 myst-parser
 numpy