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.
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.
The result is saved in the
sigasi-doc folder in the root of your project.
Since Sigasi 2.27 this export also saves the DocBook source code, if you have a Sigasi Studio XPRT license. This enables you to customize the pdf generation flow to your liking. Users without a Sigasi Studio XPRT License can also export a pdf, but it will contain a watermark.
Since Sigasi Studio 4.5 it is possible to export to HTML directly in addition to the pdf export. There are 3 options to export the documentation.
- Create a HTML document with linked diagrams. All Block Diagrams and State Machine Diagrams are in separate files which are linked from within the HTML document.
- Create a HTML document with embedded diagrams. The Block Diagrams and State Machine Diagrams are embedded in the HTML document. The documentation is in a single file.
- Create a PDF document.
All errors are logged to the console view.
The exported documentation also includes statemachine 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.
The templates used for the pdf documentation can be copied and modified in the workspace so that template customizations are not overwritten by updates of Sigasi Studio.
- Create a new folder in the workspace:
- Copy the desired template from
/plugins/com.sigasi.hdt.docgen.resources_to the /templates /.metadata/sigasi-templatesfolder.
- Now edit the
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:
The Formatter and Structural select respect (and fix) comments according to the association rules.
- 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.
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 (
- strong (
- tables (with alignment)
- external links and email addresses (