欢迎来到 Sphinxcontrib-mermaid demo 的文档！

https://travis-ci.com/mgaitan/sphinxcontrib-mermaid.svg?branch=master

这个插件允许你在你的文档中嵌入 Mermaid 图形，包括一般的流程图、序列图和甘特图。

它添加了一个指令来嵌入 mermaid 标记。比如说:

.. 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!

默认情况下，HTML 生成器将简单地将其呈现为一个 div 标记，class="mermaid"，注入外部 javascript、css 和初始化代码，使 mermaid 工作。

对于其他构建器（或者如果 mermaid_output_format 配置变量设置不同），插件将使用 mermaid-cli 渲染为 PNG 或 SVG 图像，然后用于适当的代码。

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 文件，方法是将文件名作为指令的参数，不需要额外内容

.. mermaid:: path/to/mermaid-gantt-code.mmd

对于 Sphinx 中的所有文件引用，如果文件名不是绝对的，它将被视为与源目录的相对值。

此外，你可以使用 mermaid 自动生成图表，使用指令 autoclasstree 来显示类的继承性。它接受一个或多个完全合格的类或模块的名称。在模块的情况下，所有找到的类将被包括在内。

当然，这些对象需要可被导入，以使其图示化。

如果给了一个可选的属性 :full:，它将显示每个类的完整层次结构。

选项 :namespace: <value> 限制了属于这个命名空间的基类。同时，旗标 :strict: 只处理在给定模块中严格定义的类（忽略从其他模块导入的类）。

例如

.. autoclasstree:: sphinx.util.SphinxParallelError sphinx.util.ExtensionError
   :full:
classDiagram BaseException <|-- Exception SphinxError <|-- SphinxParallelError Exception <|-- SphinxError SphinxError <|-- ExtensionError

或者直接使用该模块

.. autoclasstree:: sphinx.util
classDiagram SphinxError <|-- SphinxParallelError dict <|-- FilenameUniqDict DeprecationWarning <|-- RemovedInSphinx50Warning date <|-- datetime Exception <|-- FiletypeNotFoundError dict <|-- DownloadFiles Exception <|-- SkipProgressMessage SphinxError <|-- ExtensionError Generic <|-- IO

安装

你可以用 pip 安装它

pip install sphinxcontrib-mermaid

然后在你项目的 conf.py 的 extensions 列表中添加 sphinxcontrib.mermaid

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

指令选项

:alt:：决定了图片在HTML输出中的替代文本。如果没有给出，备用文本默认为 mermaid 代码。

:align:：决定图像的位置。有效选项是 'left'、'center'、'right'

:caption:：可以用来给图表加一个标题。

配置值

mermaid_output_format

在建立 HTML 文件时，Mermaid 的输出格式。这必须是 'raw' 'png' 或 'svg'；默认是 'raw'。如果不是 'raw'，则需要 mermaid-cli

mermaid_version

mermaid 的版本，将用于解析 HTML 文件中的 raw 输出。这应该与 https://unpkg.com/browse/mermaid/ 上的版本一致。默认的是 "latest"。

如果它被设置为 ""，lib 不会从 CDN 服务中自动包含，你需要在 html_js_files 中把它作为一个本地文件加入。例如，如果你下载 lib 到 _static/js/mermaid.js，在 conf.py

html_js_files = [
   'js/mermaid.js',
]

mermaid_init_js

Mermaid 初始化代码。默认为 "mermaid.initialize({startOnLoad:true});".

在 0.7 版更改: init 代码不再包括 <script> 标签。它是在构建时自动添加的。

mermaid_cmd

用于调用 mermaid-cli 程序的命令名称。默认是 'mmdc'；如果它不在可执行的搜索路径中，你可能需要将其设置为完整的路径。

mermaid_cmd_shell

当设置为 true 时，shell=True 参数将被传递给进程执行命令。这允许在 Windows 上执行二进制可执行文件以外的命令。默认为 false。

mermaid_params

对于单个参数，可以添加一个参数列表。请参考 https://github.com/mermaidjs/mermaid.cli#options。例如

mermaid_params = ['--theme', 'forest', '--width', '600', '--backgroundColor', 'transparent']

这将呈现主题 forest、600px 宽度和透明背景的 mermaid 图。

mermaid_sequence_config

允许覆盖序列图的配置。它对增加角色之间的宽度很有用。它 需要是一个 json 文件，检查 文档中的选项

mermaid_verbose

在调用 mermaid-cli 时使用 verbose 模式，并在构建过程中显示其输出。

mermaid_pdfcrop

如果使用 latex 输出，将 pdf 裁剪到需要的空间可能是有用的。为此，可以使用 pdfcrop。说明二进制名称来使用这个额外的功能。

Markdown support

你可以在 Sphinx 的 Markdown 文档中包含 Mermaid 图表。你只需要通过 myst-parser 在 Sphinx 中设置 markdown 支持 。请看测试中的 最低配置

然后在你的 .md 文件中包括一个代码块，如 reStructuredTexts

```{mermaid}

    sequenceDiagram
      participant Alice
      participant Bob
      Alice->John: Hello John, how are you?
```

索引和表格