Customize documentation from Sigasi Visual HDL using the Document Object Model

This article discusses how documentation, generated by Sigasi Visual HDL (SVH), can be thoroughly customized to your needs.

In an earlier article, we have explained why HDL projects benefit from good documentation, and how SVH 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 (.svg) files.

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 SVH. 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.

DOM libraries exist for multiple programming languages, including JavaScript, C/C++, Java and Python. In our example we’ve used htmldom 2.0  (documentation ), a Python  package for HTML parsing and DOM operations. Though fairly old (latest release in 2012), we found it easy and straightforward to use.

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 (href).

This script is only a small example of how you can customize the documentation generated by SVH. 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.