Documentation Generation

The Sigasi Studio documentation generator makes the documentation process easier by automatically extracting information from your HDL source files. The biggest advantage is that there is only a single source for both your design and your documentation. While this gives no guarantee for the design staying in sync with the documentation, it certainly makes it easier.

The Sigasi documentation generator has following advantages:

  • No special coding requirements: the plain comments in your code are extracted for the documentation, no need for special annotations. Sigasi uses the same comment association as the hover provider. So to document a port, you append a comment to a port declaration. To document an architecture, you put the comment just on top of the architecture.
  • All included. All documentation processing is done in Sigasi/Eclipse. So you do not need to install extra tools.
  • Fully hyperlinked. If you export the documentation, you get a fully hyperlinked document.
  • Live preview: you can see what the documentation will look like while you type your code and comments.

Export Documentation

You can export documentation for the entire project or a specific toplevel by clicking the save icon on top of the Documentation View or via the Export… menu.

  • When you select the entire project, the design elements will be listed in alphabetical order.
  • When you select a specific toplevel, design elements will be ordered in a breadth-first order from the top down.

The resulting HTML file is saved in the sigasi-doc folder in the root of your project. The generated Block and State Machine Diagrams are saved in subfolders of the sigasi-doc folder.

Sigasi Studio 4.5 introduced exporting the documentation to HTML. You have to choose between Linked resources and Embedded resources when exporting the documentation.

  • Linked resources
    Creates an HTML document with linked resources. All Block Diagrams and State Machine Diagrams are in separate files which are linked from within the HTML document. The custom CSS file, if present in the project root, will be referenced from the HTML document.

  • Embedded resources
    Creates an HTML document with embedded resources. The documentation is in a single file. The Block Diagrams and State Machine Diagrams are embedded in the HTML document. The CSS from the custom CSS file, if present in the project root, will be included in the HTML <head>.

Any errors are logged to the console view.

Customization

Sigasi Studio 4.17 introduced pagination and the introduction and problems section.

Pagination and problems configuration

Pagination

Enabling the Split pages by elements count will paginate the output documentation. This is useful for very big designs that produce documentation 100’s of MBs large.

The summary information about the design appears on the first page and fans out to subsequent pages that will contain the documentation about individual design elements.

Paginated documentation

Problems section

Enabling Include problem information will add a Problems section containing all the project’s Errors, Errors and warnings, or Errors, warnings, and infos. On top of that, the suppressed problems can also be shown.

Problems reported in the HTML documentation

Introduction section

If a sigasi-doc.md file is present in the root directory of your project, Sigasi will automatically include it in the exported documentation as an introductory chapter.
As usual with our documentation, this is a MarkDown file. This allows you to easily annotate the text.

Further customization

The exported HTML documentation can be further processed, as explained in Use a Word macro to Scale Diagrams in HTML documentation.

Graphics

The exported documentation includes the Dependency Diagram, State Machine and Block Diagrams. If you created custom graphics configurations for one or more of your diagrams, these will be used instead of the default diagrams.

If you have multiple graphics configurations for the same diagrams, the alphabetically first one is used.

Custom CSS

If the root of your project contains a sigasi-doc.css file, this file will be used to style the generated HTML documentation. Note that only the generated HTML will be affected and not the Documentation View.

For example, you can give the background and titles different colors. You can also change the font for the entire document or parts of it.

body {
   background-color: Azure;
   font-family: sans-serif;
}

h1 { color: Tomato; }
h2 { color: Orange; }
h3 { color: Gold; }
h4 { color: Aquamarine; }
h5 { color: BlueViolet; }

Entire sections for entities, architectures and modules can be given different background colors. Likewise the list of processes can get a different background color.

.entity, .module { background-color: AliceBlue; }
.architecture    { background-color: Cornsilk; }
.processes       { background-color: WhiteSmoke; }

Tables can be made striped. Within sections, you can specify different colors for the striped table.

tr:nth-child(even) { background-color: Lavender; }
.entity table tr:nth-child(even) { background-color: FloralWhite; }

It’s also possible to hide parts from view.

#revision { display: none; }

The difference in documentation with the CSS settings described above is shown in the screenshots below.

Comment Association

Comments in HDL code are used to add extra information or documentation to that code. Sigasi Studio uses certain rules to determine which comment belongs to which code. This is important for documentation hovers, refactoring, formatting,… Which comment belongs to which exact code is subjective.

Sigasi Studio associates comments with HDL declarations with following rules:

  • If there is a declaration before a comment in the same line (trailing comment), the comment is associated with this declaration. This comment can span multiple single line comments if they are aligned.
  • If there is no trailing comment and there is a comment with the same indentation on the line above the declaration, the comment is associated with this declaration. This comment can span multiple lines if all comments have the same indentation.
  • Empty lines break comment blocks

The association rules are illustrated in the image below:

comment association rules

The Formatter and Structural select respect (and fix) comments according to the association rules.

Special cases

  • VHDL components and component instantiations: If a component (or one of its ports or generics) does not have comment itself, Sigasi Studio will use the comment of the corresponding entity. This also works for component instantiations.

Comment markup with Markdown

VHDL and SystemVerilog comments are processed with a Markdown processor. This allows to add markup (e.g. bold, code, paragraphs, hyperlinks,…) to comments. This results in nicer hovers and documentation.

Markdown in comments

In hovers the complete Markdown syntax is supported. For documentation generation following features are supported:

  • paragraphs (add and empty comment line to break paragraphs)
  • line breaks (by adding two trailing spaces)
  • emphasis (*emphasis*)
  • strong (**strong**)
  • lists
  • tables (with alignment)
  • external links and email addresses (<https://www.sigasi.com>, [Sigasi](https://www.sigasi.com) and <sales@sigasi.com>)

Sigasi Studio 4.6 added support for Fenced Code blocks in comments. This enables you to add text to the documentation without Markdown rendering. To add a comment verbatim to the documentation, surround it with with triple back ticks: ```<verbatim comment>```