sphinx-rtl

A Python package to build docs for any RTL codes (VHDL, Verilog, SystemVerilog ...*) and related programs (cocotb). Operate in three steps :

1. Extracting the data from the built AST and CST
2. Inferring elements by performing an analysis of the fetched nodes.
3. Render of the inferred elements into docutils nodes.

It is designed to offer the lowest friction as possible for the user, by removing most of the documentation process. The code says enough to be used !

Main features

What make Sphinx-RTL better than others ? There are two points :

• IR documentation pass : By reading the intermediate representation after parsing the file, we can extract more information : Related clock, CDC, nets groups, outputs ...
• Git integration : The tool natively read your repo and search for commits, tags, author, messages ... No need to configure that in the top of the file.

An example could be found here

How to use it ?

1. Install the extension. It's available on PyPi, so :

pip install sphinx-rtl

2. Add the extension to the project :

Add this line in the conf.py file you used for your sphinx documentation.

extensions = ["sphinx-rtl"]

3. Configure the used files :

Add this line, configured as you need in the main rst file.

.. rtl-autodoc:: ../examples/systemverilog/*.sv
.. rtl-autodoc:: ../examples/vhdl/*.vhd

4. Run sphinx as you always did

Advanced usages

More advanced users may want to fine the output documentation. For this, sphinx-rtl propose a three level system :

All the arguments are reusing an older syntax scheme, close to what Doxygen proposed. This look like :

@warning This module must be held in reset for at least 10 clock cycle.

But, unless Doxygen, all of them are fully optional. Sphinx-RTL could perfectly run without any of them, and still produce a decent option. The approach retained was an additive process : You can only add element to the documentation.

List of the flags :

Configuration flags

These flags target the user, by enabling or disabling features for the final render.

@warning This module must be held in reset for at least 10 clock cycle.

List of the flags :