NotImplementedError: unknown node: mermaid

[cvergari]

Hi,

is there any plan to add support for sphinxcontrib.mermaid?

Currently, if I add restbuilder and mermaid in conf.py:

extensions = ['sphinxcontrib.restbuilder',
              'sphinxcontrib.mermaid']

And then add a diagram in a rst file:

This is a graph:

.. mermaid::

   graph LR
      id1[Item1] --> id2[Item 2];
      id2 --> id3[Item 3];

I get an NotImplementedError: Unknown node: mermaid.

Thanks in advance!

My environment:

Sphinx 4.2.0
sphinxcontrib-applehelp 1.0.2
sphinxcontrib-devhelp 1.0.2
sphinxcontrib-htmlhelp 2.0.0
sphinxcontrib-jsmath 1.0.1
sphinxcontrib-matlabdomain 0.12.0
sphinxcontrib-mermaid 0.7.1
sphinxcontrib-qthelp 1.0.3
sphinxcontrib-restbuilder 0.3

[macfreek]

Thanks for the feature request. The bad news is that I have no current plan to actively add support for non-standard extensions. The good news is that I would gladly accept pull requests for it!

If you are interesting in making a pull request, I am absolutely willing to give you a few pointers if you get stuck.

[cvergari]

Thanks for the info. I'd love to contribute but I am afraid I really would not know where to start!

[mbhynes]

Just passing by but I think this is relatively straightforward to resolve, probably with just a little hack in your own project's conf.py:

Problem

• The root cause here is that the .. mermaid directive isn't recognized by docutils unless it's registered as a node class
• The sphinxcontrib.mermaid extension adds a node using sphinx's add_node API in the sphinxcontrib.mermaid's setup() function, which is abbreviated below:

[...]
class mermaid(nodes.General, nodes.Inline, nodes.Element):
    pass

def html_visit_mermaid(self, node):
    render_mm_html(self, node, node['code'], node['options'])

[...] 
def setup(app):
    app.add_node(mermaid,
                 html=(html_visit_mermaid, None),
                 latex=(latex_visit_mermaid, None),
                 texinfo=(texinfo_visit_mermaid, None),
                 text=(text_visit_mermaid, None),
                 man=(man_visit_mermaid, None))

• In the above, nodes are added for each builder name in the **kwargs (ie html is for the html builder)
• If you are rolling out your own builder in an extension, you would need to have an add_note(mermaid, yourbuilder=(html_visit_mermaid, None)) call added to the app

Example Solve

• The solve is relatively straightforward: just register a node for the builder name
• It's possible to add this into a local project's extension's setup(app) such as:

from sphinx.util import logging

def setup(app):

  if 'sphinxcontrib.mermaid' in app.config.extensions:
    try:
      from sphinxcontrib.mermaid import html_visit_mermaid, mermaid
      app.add_node(
        mermaid,
        somebuilder=(html_visit_mermaid, None),
      )
    except ImportError:
      logging.getLogger(__name__).error(
        "sphinxcontrib.mermaid was detected in conf.py extensions=[...] "
        "but we were unable to import html_visit_mermaid from to run app.add_node(mermaid)."
      )