NotImplementedError: unknown node: mermaid

[kmitro]

Hi, Is it possible to add sphinxcontrib.mermaid as a supported module for confluencebuilder?

extensions = [ 'sphinx.ext.todo', 'recommonmark', 'sphinxcontrib.mermaid','sphinxcontrib.confluencebuilder' ]

Publishing in confluence is not working due to the following error:

Running Sphinx v3.5.1 running in headless mode, starting Xvfb Xvfb is running on display :0 WARNING: html_static_path entry '_static' does not exist building [mo]: all of 0 po files building [confluence]: all source files updating environment: [new config] 8 added, 0 changed, 0 removed

...

Exception occurred: File "/usr/local/lib/python3.6/site-packages/sphinxcontrib/confluencebuilder/translator/init.py", line 132, in unknown_visit raise NotImplementedError('unknown node: ' + node_name) NotImplementedError: unknown node: mermaid The full traceback has been saved in /tmp/sphinx-err-0jftiuxo.log, if you want to report the issue to the developers. Please also report this if it was a user error, so that a better error message can be provided next time. A bug report can be filed in the tracker at https://github.com/sphinx-doc/sphinx/issues. Thanks!

[jdknight]

The last investigation to support sphinxcontrib.mermaid was discussed in #159. At that time, it appeared that there was not a way to gracefully support this extension (without introducing a maintenance dependency on that project).

There have been updates to that extension since it was last looked at, so it can be investigated again to see if any new changes might improve the integration between these two extensions.

[hason]

It is possible to use sphinxcontrib.kroki which converts mermaid to svg image.

[kmitro]

@hason sphinx + mermaid works fine for me. I even able to push the stuff to GitLab pages. I get this error on the Confluence pushing stage (via confluencebuilder). With all other types of documents confluencebuilder works good for me.

[jdknight]

Reviewing the implementation again, there currently exists no stock support between these two extensions. At this time, confluencebuilder still only supports direct extension implementation for extensions found in the internal Sphinx repository.

It is possible to use confluencebuilder with sphinxcontrib-mermaid with the following modification to a documentation's configuration file:

from docutils import nodes
from sphinxcontrib.mermaid import MermaidError
from sphinxcontrib.mermaid import logger as mermaid_logger
from sphinxcontrib.mermaid import mermaid
from sphinxcontrib.mermaid import render_mm

def generic_visit_mermaid(self, node):
    try:
        fname, _ = render_mm(
            self, node['code'], node['options'], 'png', 'mermaid')
    except MermaidError as exc:
        mermaid_logger.warning('mermaid code %r: ' % node['code'] + str(exc))
        raise nodes.SkipNode

    img_node = nodes.image(uri=fname, alt=node.get('alt', ''))
    if 'align' in node:
        img_node['align'] = node['align']
    node.replace_self(img_node)
    self.visit_image(img_node)

def generic_depart_mermaid(self, node):
    pass

def setup(app):
    app.add_node(mermaid,
        confluence=(generic_visit_mermaid, generic_depart_mermaid),
        override=True)

The above will work by converting the mermaid diagrams to pngs, replace the node to an image type, which in turn will allow this extension to handle the image asset. Using svg may work as well, but has not be tested. Conversion does require configuring the mermaid_cmd option to be set.

As discussed in #159, raw (default) mermaid diagrams cannot be supported since (stock) Confluence publish events do not support injecting Javascript into a page/instance.

[kmitro]

I added all above in the config file. Also added one more import:

from docutils import nodes

get the following error:

WARNING: command 'mmdc' cannot be run (needed for mermaid output), check the mermaid_cmd setting Exception occurred: File "/usr/local/lib/python3.6/site-packages/sphinxcontrib/confluencebuilder/translator/storage.py", line 2186, in _escape_sf data = data.replace('&', '&') AttributeError: 'NoneType' object has no attribute 'replace' The full traceback has been saved in /tmp/sphinx-err-3pk490_0.log, if you want to report the issue to the developers. Please also report this if it was a user error, so that a better error message can be provided next time. A bug report can be filed in the tracker at https://github.com/sphinx-doc/sphinx/issues. Thanks!

[jdknight]

@kmitro,

You are correct that the above example will also need from docutils import nodes as well. Thanks for pointing it out, and I have updated the previous comment to reflect this (just in case someone else may stumble across this thread).

There is a change on the main branch which will prevent the use case where incomplete image nodes provided by mermaid (or any other extension) will now be suppressed (see #490). This should prevent the AttributeError exception noted.

WARNING: command 'mmdc' cannot be run (needed for mermaid output), check the mermaid_cmd setting

To ensure images are generated for the confluencebuilder extension to use, mermaid-cli must be installed for the host to build these images (since JavaScript rendering is not supported). The installation of this command will vary per host, but an example configuration for a Windows environment may be as follows:

mermaid_cmd = './node_modules/.bin/mmdc.cmd'
mermaid_output_format = 'png'

Although, it is best to consult the mermaid-cli's README for the most recent/helpful information.

[jdknight]

Support for this has been added in this extension with the idea that it might be easier for users; and hopefully does not become a maintenance issue. Support for sphinxcontrib.mermaid have been added in #522; currently on the development branch and should be available next release (v1.7+).

Note that users will still need to configure mermaid_cmd to properly render mermaid images on a Confluence instance.

[jdknight]

v1.7 is now available on PyPI -- marking as closed.