Almost a year ago, we’ve posted an article on advanced customization of the documentation generated by Sigasi Studio. In the article, we’ve demonstrated the use of the Document Object Model (DOM) and Python to alter the HTML code of the generated documentation. The article contains a fully elaborated example, as well as some suggestions of other use cases that the DOM could handle.
Lately, a customer challenged us to substantiate our claims about those additional use cases. Well, we don’t mind a small challenge, so one Friday afternoon we switched our focus from VHDL and Verilog to HTML and Python. In particular, the customer asked whether we could help with
- adding a company logo near the top of the file, and
- removing one or more sections from the documentation
And, yes, we can!
In fact, the following piece of code is all you need to add a logo,
and to remove the documentation of SystemVerilog
from htmldom import htmldom # Parse the generated documentation dom = htmldom.HtmlDom("file:documentation.html").createDom() # Add a logo after the title. You can make the markup fancier if desired. dom.find("h1.title").after('<img src="company_logo.png">') # Remove the (System)Verilog "always" blocks from the documentation. # # "always" blocks in the documentation are surrounded by # <div id="...always-blocks"> all_divs = dom.find("div") for div in all_divs: if str(div.attr("id")).endswith("always-blocks"): div.remove() # Save the altered documentation with open('new_documentation.html', 'w') as f: f.write(dom.find("html").html())
After reading the generated documentation, the script first adds a
logo after the main title (
<h1 class=title>). Then, it looks up and
<div> blocks of which the id ends with
always-blocks. Finally, the resulting document is saved as a new
While this looks simple, it may not be obvious to come up with the right htmldom API calls, or which elements to look for in the generated documentation. The htmldom API is documented here, but this documentation is not very clear so you may need some additional online searching with dr. Google and the like. When it comes to finding elements in the documentation, a first option that comes to mind is simply opening the generated HTML in a text editor. While that will work, web browsers often have a feature to inspect HTML which makes one’s life much easier, as shown below. One caveat - note that the structure of the generated documentation is not fixed like an API, so it may happen that HTML tags change with a new version of Sigasi Studio.
Now it’s up to your creativity again. 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.
- Customize documentation from Sigasi Studio using the Document Object Model (blog post)
- Generate documentation in Sigasi Studio (blog post)
- Generate VHDL documentation in Sigasi Studio (blog post)
- The benefits of early detection (screencast)
- Documentation features for large designs in Sigasi Studio (blog post)