This article discusses how documentation, generated by Sigasi Studio, can be thoroughly customized to your needs.
In an earlier article,
we have explained why HDL projects benefit from good documentation,
and how Sigasi Studio can extract HTML documentation from your HDL
code and comments. The extracted documentation is written as a single,
fully hyperlinked HTML file. Graphics such as state machine and block
diagrams can be either embedded in the HTML file, or written as
separate graphics (
To some extent, the generated documentation can be restyled using Cascading Style Sheets (CSS). CSS are preferred for changing colors and fonts and they also allow to hide entire sections from the document. But their primary purpose remains the custom styling of the generated documentation.
In some cases more advanced control of the documentation is required. You may want to extract and aggregate information from it or you want to split the documentation in separate files per design unit. Or you may want to add information (e.g. a company header), or reorder the design units in the document. In that case, a more advanced approach than CSS is required.
The method which we’ll introduce here starts from the single HTML file generated by Sigasi Studio. We’ll demonstrate how this file can be parsed into a collection of elements, and how these elements can be accessed, adapted and rearranged. Note that a minimum of programming or scripting skills is required to use the presented method.
Note that the structure of the generated documentation is not fixed like an API. In future versions, Sigasi may change the way in which documentation is generated. As a consequence, scripts which extract information from the generated documentation may break. This article and the scripts herein are based on Sigasi Studio 4.12.
The Document Object Model
Parsing generated documentation may seem daunting. Fortunately, the Document Object Model (DOM) is there to help. In the DOM, an HTML (or XML) document is represented as a tree of objects. Each object is a part of the document, e.g. a title, a paragraph, a hyperlink, a table… Software libraries exist to parse an HTML file into a DOM object tree and to access and manipulate the DOM tree.
An example: splitting the documentation by design unit
This script is an example of how the DOM can be used to extract data from the documentation. It is up to the reader to modify the script for their needs. Here’s a summary of what the script does:
- Open and parse the documentation.
- Extract VHDL entities and architectures, and (System)Verilog modules.
- Make a list of entities and modules which are instantiated i.e. not at the top of the design hierarchy. In the same process, a link to the instantiated entity or module is inserted.
- Prepare an index document (
index.html) to contain a list of design units.
- Create a separate HTML file for each design unit. If the design unit is at the top level of the design (i.e. not instantiated in any other design unit), this is mentioned in the HTML. Also, the design unit is added to the index.
- Write and save all HTML files.
In the script, you’ll notice that opening and parsing the input file
only takes a single line of code. Also, the newly created HTML
documents are mostly concatenations of parts (sub-trees) of the
original one. The
find() method is used frequently to look up
particular tags. By reusing entire HTML DOM sub-trees, new documents
can be put together with minimal effort. We also demonstrate how to
make changes to the document, e.g. inserting text indicating a
top-level design unit, or adding a link (
This script is only a small example of how you can customize the documentation generated by Sigasi Studio. Using the DOM, one can do many more things, such as
- adding a company header and copyright notice in the appropriate place,
- re-ordering design units in the document,
- effectively removing internal details from the document (rather than hiding them using CSS) (e.g. when sharing your IP block’s documentation with a customer),
- … or anything creative that you may come up with.
Note however that we don’t recommend to extract the compilation order of the design files from the documentation. If you need to generate the compilation order, we recommend to export it directly as a CSV file.
Did you make a cool script to share? Let us know! If necessary, Sigasi license holders may also contact support. We’ll help you as best as we can.
- Generate documentation in Sigasi Studio (blog post)
- Customizing documentation from Sigasi Studio: easier than you think (blog post)
- Generate VHDL documentation in Sigasi Studio (blog post)
- Documentation features for large designs in Sigasi Studio (blog post)
- The benefits of early detection (screencast)