How to Run Specador Documentation Generator in Batch Mode

Overview

Specador generates accurate HTML and PDF documentation from source code and comments, including type and design hierarchies, class, module and finite-state machine diagrams, as well as review-oriented sections like coverage or checks.

This video shows how to use the Specador command line executable: the basic switches are explained and exemplified.

By automating the documentation process using Specador, you can always keep the documentation in sync with the source code.

Explore the design and verification tools: https://eda.amiq.com/
Or request a license: https://eda.amiq.com/request-license

Specador User Guide: https://eda.amiq.com/documentation/specador/index.html

This video was shot using Specador 24.1.17.

Details

Introduction

Specador generates accurate HTML and PDF documentation from source code and comments, including type and design hierarchies, various diagrams for module schematics, testbench architecture, timing diagrams or finite state machines, as well as summary sections, such as coverage or checks.

Basic Usage of Specador

Specador helps you keep the documentation in sync with the source code by automating the documentation process.

A simple Specador invocation takes two arguments: -lang, to specify the language of your project, for example, Verilog and VHDL, as wel as the actual compilation arguments you would pass to any simulator using -cmd.

This is because Specador uses its built-in compiler to analyze the code and understand the project structure. When done, the path to the index.html file is printed. Open it in a web browser to visualize the generated documentation.

Visualizing the Generated Documentation

Use the search bar or select an element from the table of contents. Scroll the page to read through the automatically extracted description of the entity and identify its generics and ports for which Specador has embedded comment descriptions found in the source code. You have the option to choose between different markup languages to format the comments, such as reStructuredText or Markdown.

Customizing the Generated Documentation

To customize the generated documentation, use -preferences to point to a preferences XML file. The available preferences are documented in the Specador User Guide. For example, you may filter out specific elements and indicate what diagrams to generate.

You can customize the table of contents using the -index arguments if you want, for example, to promote specific pages. To link additional documentation, you can provide files written in either reStructuredText or Markdown using the -attach argument.

Generating PDF Documentation

To generate PDF documentation, use the -pdf argument on the command line. Note that PDF generation requires specific packages to be available on your system. For details, consult the user guide section linked in the video description.

Handling Compilation Errors

By default, if Specador detects errors during compilation, it won't proceed to the generation phase in order to prevent inaccurate documentation. You may choose to waive specific errors or force the documentation generation by passing the -ignore_compile_errors argument.