# 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](../../requirements.txt)
## Document Python Code
Python code can be documented via docstrings. A good and universal explanation can be found [here](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html)
## Document VHDL Code
The sphinx-vhdl.vhdl extension can generate code for vdhl and vhd files. The original documentation can be found [here](https://cesnet.github.io/sphinx-vhdl/index.html).
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
1. between the `--` and your text has to be a space:
good: `-- test string`
bad: `--bad string`
2. 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](https://myst-parser.readthedocs.io/en/v0.18.1/index.html).
```{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](https://www.markdownguide.org/basic-syntax/).
### 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.
```markdown
% 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](https://docutils.sourceforge.io/docs/ref/rst/roles.html), [docutils directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html), [sphinx roles](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html) and [sphinx directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) 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:
````markdown
```{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
```python
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
```{code-block} python
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](tables) and [figures and images](imagesfigures).
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:
```markdown
{role-name}`role content`
```
For example:
```
{math}`1+2 = 3`
```
renders as
{math}`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:
```markdown
(testreference)=
# Some headline
This is an example.
[This reference](testreference) will jump to the headline.
```
Alternative syntax for the clickable link is
```markdown
{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
````
``` markdown
# hello
```
````
`````
% ### Bibliographie ???
### Footnotes
To add a footnote, use the following syntax:
```markdown
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.[^longnote]
[^1]: Here is the footnote.
[^longnote]: Here's one with multiple blocks.
### Embed other files
To include links to other files e.g. documents in the pdf format, use the following syntax:
```markdown
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](doc/zybo-z7_rm.pdf).
```{note}
The link will not be usable in the pdf version of the document.
```
(tables)=
## Tables
To create tables the [Github Markdown Syntax](https://github.github.com/gfm/#tables-extension-) can be used.
Use pipes `|` to separate columns and hyphens `-` to create a header row.
```markdown
| 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.
```markdown
| 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 |
(imagesfigures)=
## 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:
```markdown
```
this will render as:
### MySt Syntax
To include an image in a MySt file, use the following syntax:
````markdown
```{figure} figs/thanna_logo.svg
:scale: 0.1
:alt: Alt text
:align: center
Caption text
```
````
this will render as:
```{figure} figs/thanna_logo.svg
:scale: 20
:alt: Alt text
:align: center
Caption text
```
```{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](https://myst-parser.readthedocs.io/en/v0.18.1/syntax/roles-and-directives.html#images-and-figures)
```
## Using draw.io diagrams
When creating diagrams for the documentation with [draw.io](https://app.diagrams.net/)
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.