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.
• Plugin integration : Add any custom Python code to edit on the fly the rendered page ! This enables NDA status, brands customizations or even CI/CD status network fetch !

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"]

Even if the extension does support any width of prints via the support of lateral scrollbar, It's recommended to add these lines to your conf.py file

html_theme_options = {
    "page_width": "1800px",
    "body_max_width": "auto",
    "sidebar_width": "280px",
}

This will make the reading wider, fitting the tables used with a cleaner aspect.

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

ℹ️ INFO The extension support to modes of adding files :

• glob (, **/) and any valid syntax to the python glob module
• specific files.

To be noted : When the glob mode is used, all the modules found will be added to a single page, with all the elements. This can be especially useful for different but similar modules, but shall not be used as a primary documentation method.

ℹ️ INFO The extension also enable some aliases :

• vhdl-autodoc
• sv-autodoc They all do the same, without any differences.*

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 :

Plugin integration

Sphinx-rtl does not handle plugin individually, it rather depends on the native Sphinx plugin management. Therefore, natively the plugin emit events that you can fetch by writing your own Sphinx extension, and listen to them.

ℹ️ INFO Sphinx-RTL provide a "user" field into each Component object, free for the user. This enables passing data between events and to the rendering pass without having to maintain a dict of elements.

By default, this "user" field is simply ignored by any rendering pass.

Emitted events :