Skip to main content

Generate diagrams from Verilog in Sphinx.

Project description

PyPI PyPI version Documentation Build Status codecov

Sphinx Extension which generates various types of diagrams from Verilog code.

sphinxcontrib-verilog-diagrams is a Sphinx extension to make it easier to write nice documentation from Verilog files. It primarily uses Yosys to do the Verilog reading.

Check out the documentation for examples.


Python 3.5+ is required.

pip install sphinxcontrib-verilog-diagrams


python3 -m pip install sphinxcontrib-verilog-diagrams

Sphinx Integration

In your, add the following lines.

extensions = [

Non-Python Dependencies

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

conda XXXX





The verilog-diagram RST directive can be used to generate a diagram from Verilog code and include it in your documentation. Check out the examples to see how to use it.

.. verilog-diagram:: file.v
   :type: XXXXX
   :module: XXXX
   :skin: XXXX
   :yosys_script: 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.


Here is a diagram of a 4-bit carry chain.

4-bit carry chain


This extension also provides the no-license directive which can be used to include code blocks from a file, but omitting the license header at the top of the file. It behaves like the literalinclude directive, but the lines option is overridden to only show the lines after the license header.

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


Here is a comparison between the literalinclude and no-license directives.

.. literalinclude:: verilog/dff.v
   :language: verilog
   :caption: verilog/dff.v
 * Copyright (C) 2020  The SymbiFlow Authors.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * SPDX-License-Identifier: Apache-2.0

// Single flip-flip test.
module top(input clk, input di, output do);
  always @( posedge clk )
    do <= di;
endmodule // top
.. no-license:: verilog/dff.v
   :language: verilog
   :caption: verilog/dff.v
// Single flip-flip test.
module top(input clk, input di, output do);
  always @( posedge clk )
    do <= di;
endmodule // top


Apache 2.0

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page