sphinxcontrib-yowasp-wavedrom

这个Sphinx扩展允许在Sphinx文档中嵌入WaveDrom波形、位字段和电路图。

此扩展使用YoWASP WaveDrom包来确保图表的渲染与WaveDrom编辑器中完全相同，无需遵循配置决策树，无需在用于构建文档的系统中安装任何额外工具，无需在该系统上安装任何本地依赖项，无需JavaScript浏览文档，也不会减慢Sphinx构建过程。它还会报告语法和语义错误，并准确报告源位置。

WaveJSON图表描述始终转换为SVG文件；目前只支持HTML构建器。请务必遵循颜色方案部分的说明！

用法

此扩展仅提供一个指令，即wavedrom。其参数是生成图像文件的基名，不带扩展名（在<输出目录>/<文档目录>/_images/中；对于该文档目录必须是唯一的），其内容是可从编辑器复制或粘贴的原始WaveJSON文件。例如

.. wavedrom:: clk_and_data

    {"signal": [
        {"name": "clk",  "wave": "n..."},
        {"name": "data", "wave": "01.0"}
    ]}

此扩展也接受更易于人类阅读的JSON5格式的WaveJSON文件

.. wavedrom:: clk_and_data

    {signal: [
        {name: 'clk',  wave: 'n...'},
        // a single pulse
        {name: 'data', wave: '01.0'},
    ]}

更多示例可在测试套件中找到，以及相应的渲染输出。

颜色方案

默认情况下，图表会对用户代理提供的首选颜色方案做出响应。这通常不是期望的行为，除非扩展与选择的Sphinx主题集成，否则可能会使图表难以阅读。

对于只有浅色变体的 Sphinx 主题，例如 Read the Docs 主题，应使用以下 自定义 CSS：

img.wavedrom { color-scheme: light; }

对于具有浅色和深色变体以及切换按钮的 Sphinx 主题，例如 Furo 主题，以下自定义 CSS 可以作为起点：

:root[data-theme="light"] { img.wavedrom { color-scheme: light; } }
:root[data-theme="dark"] { img.wavedrom { color-scheme: dark; } }

可能需要调整以适应主题跟踪动态选择的配色方案偏好的特定机制。

对于具有浅色和深色变体且没有切换按钮的 Sphinx 主题（即始终遵循用户代理偏好），默认行为是足够的。

配置

扩展在 conf.py 中识别以下配置变量

# Default skin for waveforms. If `json["config"]["skin"]` is not set in the directive,
# it defaults to the value of this variable. Does not affect bit fields or circuits.
yowasp_wavedrom_skin = "default"

许可证

本项目遵循 MIT 许可协议。