dragontao/sphinx_mermaid

镜像概述

本镜像基于Sphinx构建，集成mermaid、plantuml、needs、wavedrom、mscgen等开源插件，支持生成HTML、docx、PDF等格式文档，满足技术文档中各类图表渲染需求。

核心功能

• mermaid：渲染流程图、时序图、类图、状态图、实体关系图、旅程图、甘特图、饼图、需求图。
• plantuml：支持时序图、用例图、类图、对象图、活动图、组件图、部署图、状态图、定时图、JSON/YAML数据展示、网络图、线框界面、架构图、SDL图、Ditaa图、甘特图、思维导图、WBS图、数学公式、实体关系图。
• needs：提供需求管理功能（需求图、列表、表格、流程图、序列图、甘特图、饼图、过滤、输入图、服务图、拓展）。
• wavedrom：渲染时序图、波形图。
• mscgen：生成消息序列图。

使用场景

• 技术文档编写：快速生成含复杂图表的API文档、项目说明。
• 需求管理：通过needs插件管理项目需求并生成相关图表。
• 团队协作：统一文档构建环境，确保输出格式一致。

配置说明

mermaid配置

python
extensions.append('sphinxcontrib.mermaid')
mermaid_pdfcrop = "/usr/bin/pdfcrop" # 构建PDF时裁剪图像
mermaid_params = ['-p', '/puppeteer-config.json']

plantuml配置（可选）

python
extensions.append('sphinxcontrib.plantuml')
plantuml = 'java -jar /usr/share/plantuml/plantuml.jar'
plantuml_output_format = 'png'

needs配置

python
extensions.append('sphinxcontrib.needs')

wavedrom配置

python
extensions.append('sphinxcontrib.wavedrom')
wavedrom_cli='wavedrom-cli'

部署示例

拉取镜像

bash
docker pull docker.xuanyuan.run/dragontao/sphinx_mermaid

生成HTML文档

bash
sudo docker run -v `pwd`:/notes -w /notes dragontao/sphinx_mermaid make html

生成docx文档

bash
sudo docker run -v `pwd`:/notes -w /notes dragontao/sphinx_mermaid make docx

生成PDF文档

bash
sudo docker run -v `pwd`:/notes -w /notes dragontao/sphinx_mermaid make latexpdf