Sphinx HDL Diagrams
Sphinx HDL Diagrams

Sphinx HDL Diagrams

sphinx-hdl-diagrams is an extension to Sphinx to make it easier to write nice documentation from HDL source files, in the form of Verilog, nMigen, or RTLIL code.

You use the .. hdl-diagram RST directive to generate various styles of diagrams from HDL code.

Most of the time there will be a license header at the top of source code, which we might not want to show in the documentation. This extension also provides the .. no-license RST directive which works exactly like the .. literalinclude directive, but the lines option is overridden to only show the lines after the license header.

The project repository is hosted on GitHub.


Python 3.5+ is required.

pip install sphinxcontrib-hdl-diagrams


python3 -m pip install sphinxcontrib-hdl-diagrams

Sphinx integration

In your conf.py, add the following lines.

extensions = [

Non-python dependencies

These dependencies can either be installed on your system or you can install them using the conda environment.yml file.



The hdl-diagram RST directive can be used to generate a diagram from HDL code and include it in your documentation.

.. hdl-diagram:: file.v
   :type: XXXXX
   :module: XXXX


:type: - Verilog Diagram Types;

  • yosys-blackbox - Netlist rendered by Yosys.

  • yosys-aig - Verilog file run through aigmap before image is generated directly in Yosys.

  • netlistsvg - Render output with netlistsvg

:module: - Which module to diagram.

:flatten: - Use the Yosys flatten command before generating the image.


The no-license RST directive can be used to include code without license headers.

.. no-license:: file.v
   :language: verilog
   :caption: examples/verilog/dff.v


This directive merely overrides the lines and lineno-start options of the literalinclude directive. So, refer to literalinclude for the available options.