sphinxcontrib-wavedrom 3.0.4

Installation

The wavedrom extension can be installed using pip:

pip install sphinxcontrib-wavedrom

and by adding ‘sphinxcontrib.wavedrom’ to the extensions list in your conf.py file.

Directives

The extension is useable in the form of an extra wavedrom directive, as shown below.

.. wavedrom::

        { "signal": [
                { "name": "clk",  "wave": "P......" },
                { "name": "bus",  "wave": "x.==.=x", "data": ["head", "body", "tail", "data"] },
                { "name": "wire", "wave": "0.1..0." }
        ]}

Alternatively, it can read the json from a file:

.. wavedrom:: mywave.json

When configured to generate images (see Configuration) the directive will generate an image and include it into the input. It allows for the same configuration as the image directive:

.. wavedrom:: mywave.json
:height: 100px
:width: 200 px
:scale: 50 %
:alt: alternate text
:align: right

The image can be turned into a figure by adding a caption:

.. wavedrom:: mywave.json
    :caption: My wave figure

The extension can be configured (see Configuration) to not generate an image out of the diagram description itself, but to surround it with some html and js tags in the final html document that allow the images to be rendered by the browser. This is the currently the default for HTML output.

Configuration

The following decision tree gives an overview of which configurations to make in different use cases:

The extension can be configured to either directly output images or by emitting the javascript to live-render the wavedrom code, which obviously only works for HTML output. All other outputs (most notably latexpdf) embed a generated image in any case, but this is only supported when using Python 3.

Depending on the output you’re building, the plugin will automatically choose the appropriate image rendering method (HTML defaults to browser rendering, pdf to build-time image generation). You can force the generation of build-time images by adding the following configuration to your conf.py:

wavedrom_html_jsinline = False

This may be interesting in case you are building for various output targets and want to ensure consistent diagrams between all output formats

Examples

In the example folder, you can find a couple of examples (taken from the wavedrom tutorial), illustration the use of the extension.