Documentation guidelines

This documentation is built with Sphinx and all source code is available at the path docs.

To contribute to it, open a pull request with the changes to this repository, just make sure to read the general Documentation guidelines first and the additional guidelines below specific to the Testbenches repository.

Templates

Templates are available:

• docs/projects/ip_based/template (rendered).

• docs/projects/project_based/template (rendered).

Remove the :orphan: in the first line, it is to hide the templates from the TOC tree, and make sure to remove any placeholder text and instructive comment.

Note

The old wiki uses dokuwiki. When importing text from there, consider pandoc and the tips accross the Documentation guidelines to convert it to reST.

Common sections

The More information and Support sections that are present in the Testbenches documentation, are actually separate pages inserted as links. They’re located at testbenches/projects/common/more_information.rst and /support.rst, and cannot be referenced here because they don’t have an ID at the beginning of the page, so not to have warnings when the documentation is rendered that they’re not included in any toctree.

They are inserted like this:

.. include:: ../projects/common/more_information.rst

.. include:: ../projects/common/support.rst

And they will be rendered as sections of the page.

Warnings and messages

The warning and message directives are used for information highlighting. The different types of warnings and messages are listed and explained on the Sphinx Directives documentation page.

Here are a couple of examples:

.. note::

   This is a note.

.. important::

   This is an important message!

And they will be rendered as sections of the page.

Class hierarchy

For class inheritance and aggregation hierarchy generation the D2 Playground is used. This is helpful when changes need to be made to the hierarchy and the documentation is updated in the future. The hierarchy code must include the inheritance graph and, if applicable, the aggregation graph. All classes drawn in the graph should have a link to the documentation that explains it. Listing properties and methods is a nice to have, but not mandatory. The layout engine must be set to ELK. When generating the SVG files, the inheritance graph and the aggregation graph must be generated separately using the tool’s Export SVG function. The class hierarchy code must be saved as a .txt file and uploaded alongside the SVG files.