sphinxcontrib-yowasp-wavedrom

This Sphinx extension allows embedding WaveDrom waveform, bitfield, and circuit diagrams into Sphinx documents.

This extension uses the YoWASP WaveDrom package to ensure that diagrams are rendered exactly the same as in the WaveDrom editor, without having to follow a decision tree for configuration, without requiring any additional tools to be installed on the system used to build documentation, without requiring any native dependencies to be installed on that system, without requiring JavaScript for browsing documentation, and without slowing down the Sphinx build process. It also reports syntax and semantic errors with accurate source locations.

WaveJSON diagram descriptions are always converted into SVG files; only the HTML builder is supported at the moment. Make sure to follow the instructions in the color schemes section!

Usage

This extension provides only one directive, wavedrom. Its argument is the base name, without extension, of the generated image file (in <output directory>/<document directory>/_images/; which must be unique for that document directory), and its contents is the raw WaveJSON file that can be copied to or from the editor. For example:

.. wavedrom:: clk_and_data

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

This extension also accepts WaveJSON files in the more human-friendly JSON5 format:

.. wavedrom:: clk_and_data

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

Additional examples are available in the test suite, as well as the corresponding rendered output.

Color schemes

By default, the diagrams are responsive to the preferred color scheme as provided by the user agent. This is usually not quite the desired behavior, and can make diagrams unreadable unless the extension is integrated with the chosen Sphinx theme.

For Sphinx themes that only have a light variant, e.g. the Read the Docs theme, the following custom CSS should be used:

img.wavedrom { color-scheme: light; }

For Sphinx themes that have a light variant and a dark variant and a button that switches between them, e.g. the Furo theme, the following custom CSS may be used as a starting point:

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

It may have to be adjusted to accommodate the particular mechanism the theme is using to keep track of the dynamically selected color scheme preference.

For Sphinx themes that have a light variant and a dark variant and do not have a button to switch between them (i.e. the user agent preference is always followed), the default behavior is sufficient.

Configuration

The extension recognizes these configuration variables in 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"

Development

This project uses PDM for package management. The package supports Python 3.10+ and Sphinx 7.1 through 9.x.

Since Sphinx 9 requires Python 3.11+ while the package supports Python 3.10+, the lockfile must cover multiple Python version ranges:

# Lock for Python 3.10 (gets Sphinx 8.x max)
pdm lock --python ">=3.10,<3.11"

# Append lock for Python 3.11+ (gets Sphinx 9.x)
pdm lock --python ">=3.11" --append

To install and run tests:

pdm install --dev
pdm test

License

This project is distributed under the terms of the MIT license.