How to Document

Introduction

This page will detail how to document development on the PicoNut project using the setup provided.

Software dependencies

In order to build the documentation from the source directory, a few software packages have to be installed.

pyhton3
python3-sphinx
python3-myst-parser
python3-sphinx-rtd-theme

inkscape

Please install these packages. There are also included in the requirements.txt

Document Python Code

Python code can be documented via docstrings. A good and universal explanation can be found here

Document VHDL Code

The sphinx-vhdl.vhdl extension can generate code for vdhl and vhd files. The original documentation can be found here. The vhdl extension for sphinx can extract documentation for the following parts of your code:

package
entity
ports
enum
function
generics
constants
general types
record types

To write documentation for a part of your code just add comments directly over the pakage, entity, … This will generate a description text for your part of the code.

Gidelines for automatic documentation

between the -- and your text has to be a space:

good: -- test string

bad: --bad string

no empty lines in one description:

-- This is not a documentation comment

-- This is also not a documentation comment
--Because this comment has no space
-- This is a documentation comment for the entity
-- Here it continues
--
-- Above here is a blank line in the documentation.
-- It is still a documentation comment
entity entityName is```

Ports

You can document ports by adding the documentation next to the port description:

 -- This is a documentation for the port1
 signal port1 : inout std_logic bus := ‘1’;
 port2 : in bit    -- This is a documentation comment for port2

Parameter

You can add Parameter to your decription. Therefore you just have to add following under your original description:

-- function-description
--
-- .. vhdl:parameters:: function-name
--
--     a : in unsigned
--         description for parameter

Generic

To add a description of a generic you can just add a comment to the generic:

generic (
    -- description
    constant max_value : integer := 16
);

This will also recognice that in this generic you have a max_value from type integer with the default value 16.

Adding Documentation into sphynx

Python

In python you can automaticly generate .rst-files for your python code. For example you can generate for all modules a file with following command:

cd docs
sphinx-apidoc -o . ../quantizer/quantizer

This will generate to files:

modules.rst
quantizer.rst

The modules.rst contains a toctree with the links to all parts of the quantizer package.

The quantizer.rst contains the commands for the generation of the documentation.

Both files can be changed as wished and added to the documentation in the wanted places.

VHDL

create a .rst-file. Here you can add your own documentation with restructured text. To add generated documentation just add:

 .. vhdl:autopackage:: package_name
 .. vhdl:autoentity:: entity_name
 .. vhdl:autofunction:: function_name

If one part is the part of e.g. a package you can just add an indent to show sphinx the belonging:

 .. vhdl:autopackage:: package_name
    .. vhdl:autofunction:: function_name_of_package

How to build

To build the documentation, navigate to the docs-Folder and invoke make html. This will create a file index.html in docs/build/html which can be opened with any web browser.

Additional targets for the make command include:

make clean to clear the build files.

To see all available options use make help.

MyST parser

This documentation uses the markdown language embedded into Sphinx through the extension myst-parser. For a full documentation of the features that myst provides, navigate to the official myst-parser documentation page.

Note

Ensure that the selected version of the documentation on the previously linked page is set to 0.18.1.

Standard markdown syntax

This documentation is created using the markdown language.

A brief overview of standard markdown can be found markdownguide.org.

How to include markdown files

In order to add Markdown files in a nother file just add:

```{include} ../README.md
```

to add it into the caption (the links on the left) add it into the toctree caption:

 ```{toctree}
 :maxdepth: 2
 :caption: "Table of Contents"
 source/how_to_document.md
 ```

The path to the file is ralativ to the Makefile in the docs folder

Additional syntax provided by MyST

The MyST-parser provides a range of extra features beyond standard markdown.

Comments

Comments can be made within source .md files. For this the % symbol is used.

% comment

Directives and Roles

MyST acts as a wrapper for RestructuredText roles and directives, simplifying the syntax.

Directives and roles allow the user to format text in a predefined manner. Directives are structured as a block surrounded by backticks, roles are constructed in-line.

According to the MyST manual, all docutils roles, docutils directives, sphinx roles and sphinx directives should be functional within MyST.

A short overview over the most commonly used directives will be provided here.

Admonitions

Admonitions such as warnings and notes are created as follows:

```{note}
    This is a note.
```

will render as:

Note

This is a note.

Options include: note, warning, attention, error, hint, important and tip

Code

Code blocks can be constructed with the standard markdown syntax or the MyST provided syntax.

Standard Markdown code blocks

```python
def main():
        print("Hello World!");
```

renders as

def main():
        print("Hello World!");

MyST directive

```{code-block} $language
    code
```

Is the default syntax.

```{code-block} python
    def main():
        print("Hello World!\r");
```

renders as

    def main():
        print("Hello World!");

Tables and figures

Documentation on how to creates tables and how to include images and figures into the document can be found under tables and figures and images.

imgaes und tables verlinken

Roles

Roles in essence achieve the same things that directives do, but they are used in-line instead of requiring their own block.

The default syntax is:

{role-name}`role content`

For example:

    {math}`1+2 = 3`

renders as

\(1+2 = 3\)

References

References are useful when the user wants to create a quick and clickable reference to another section of the documentation. References can be created for headlines, images, tables and code blocks.

To begin with, a reference has to be declared at the target of the reference. The syntax for this is

(referencename)=

To create a clickable object to lead to a reference, the following snytax options can be used:

[text](referencename)

Example:

(testreference)=
# Some headline

This is an example.

[This reference](testreference) will jump to the headline.

Alternative syntax for the clickable link is

{ref}`testreference`

Nesting of Backticks

When a block encased in backticks needs to be nested in another block encased in backticks, the outer block needs to have an additional backtick at the beginning and end of the block.

````
``` markdown
# hello
```
````

Footnotes

To add a footnote, use the following syntax:

Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.
[^longnote]: Here's one with multiple blocks.

This will render as:

Here is a footnote reference,[1] and another.[2]

Embed other files

To include links to other files e.g. documents in the pdf format, use the following syntax:

Here is a link to the technical report [zybo-z7_rm.pdf](doc/zybo-z7_rm.pdf).

This will render as:

Here is a link to the technical report zybo-z7_rm.pdf.

Note

The link will not be usable in the pdf version of the document.

Tables

To create tables the Github Markdown Syntax can be used.

Use pipes | to separate columns and hyphens - to create a header row.

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

This will render as:

Header 1	Header 2	Header 3
Cell 1	Cell 2	Cell 3
Cell 4	Cell 5	Cell 6

The table can be aligned to the left, right, or center by adding colons : to the header row.

| Left-aligned | Center-aligned | Right-aligned |
| :---         | :---:          | ---:          |
| Cell 1       | Cell 2         | Cell 3        |
| Cell 4       | Cell 5         | Cell 6        |

This will render as:

Left-aligned	Center-aligned	Right-aligned
Cell 1	Cell 2	Cell 3
Cell 4	Cell 5	Cell 6

Images and Figures

Images and figures can be includes in multiple ways.

Supported Formats

The following image formats are supported:

png
jpg
jpeg
pdf
svg

Markdown Syntax

To include an image in a markdown file, use the following syntax:

![Alt text](figs/THANNA_LOGO.png)

this will render as:

Alt text

MySt Syntax

To include an image in a MySt file, use the following syntax:

```{figure} figs/thanna_logo.svg
:scale: 0.1
:alt: Alt text
:align: center

Caption text
```

this will render as:

Note

instead of the figure directive, the image directive can be used. The figure directive is used to include images with captions.
Additional options can be found in the MySt documentation

Using draw.io diagrams

When creating diagrams for the documentation with draw.io the file should be exported into either of the following formats:

.drawio.svg
.drawio.png

These files can still be edited with draw.io but can also be used in the documentation.