util/docgen/examples/README.md

# Examples using docgen

This directory has some examples of using docgen. The example commands
assume $REPO_TOP is set to the toplevel directory of the repo.

### Setup

If packages have not previously been installed you will need to set a
few things up. First use `pip3` to install some required packages:
```
$ pip3 install --user hjson
$ pip3 install --user mistletoe
$ pip3 install --user pygments
```

The examples all use the -c flag to ensure CSS styles are included
inline in the html file generated. If building a site this flag will
likely not be used. If this flag is not given then `md_html.css` from
docgen and `reg_html.css` from reggen should be put in the same
directory as the html file.

### Build example1

Example 1 is the Simple Uart. There are a couple of changes from the
actuall implemmentation: the registers are declared as 64-bit and the
STATECLR register bits have been moved up by 16 bits.

```
$ cd $REPO_TOP/util/docgen/examples
$ ../../docgen.py -c uart.md > /tmp/uartout.html
```

If you want it to tell more about progress add the verbose flag. Note
that this causes a second validation pass that checks the output of
the first pass, there should be fewer things to do on the second pass.

```
$ cd $REPO_TOP/util/docgen/examples
$ ../../docgen.py -c -v uart.md > /tmp/uartout.html
```

You can open the output using file:///tmp/uartout.html

### Build example2

Example 2 is a 16550 style Uart. This shows 8-bit registers and
registers at the same address.

Note this example has a deliberate error in the second waveform description.

```
$ cd $REPO_TOP/util/docgen/examples
$ ../../docgen.py -c uart16550.md > /tmp/uart16550out.html
```

If you want it to tell more about progress add the verbose flag. Note
that this causes a second validation pass that checks the output of
the first pass, there should be fewer things to do on the second pass.

```
$ cd $REPO_TOP/util/docgen/examples
$ ../../docgen.py -c -v uart16550.md > /tmp/uart16550out.html
```

The waveforms can also be generated using the browser-based wavedom
javascript.

```
$ cd $REPO_TOP/util/docgen/examples
$ ../../docgen.py -cj uart16550.md > /tmp/uart16550out.html
```


You can open the output using file:///tmp/uart16550out.html

### Build example 3

Example 3 is an example of using the multireg key to generate registers.


```
$ cd $REPO_TOP/util/docgen/examples
$ ../../docgen.py -c gp.md > /tmp/gpout.html
```