# Developing OBI

## Editing the documentation
OBI documentation is built with [Sphinx](https://www.sphinx-doc.org/en/master/) and the [MyST](https://myst-parser.readthedocs.io/en/latest/) Markdown parser. This configuration was chosen to combine the advanced autodocumentation features of Sphinx with the lower friction of writing in Markdown.

To install additional dependencies necessary to build the documentation:
```
pdm install -L pdm.dev.lock
```

To build the documentation:
```
pdm run docs
```

To view the documentation locally:
```
pdm run docs_serve
```
The documentation will be available at `localhost:8000`

## Environment management
Currently, we use [PDM](https://pdm-project.org/en/latest/) to install OBI in a virtual environment, so all installs are local and editable.
After [installing](installation.md) OBI, a virtual environment is created in `software/.venv`. 

### PDM Quick Reference
To add a dependency from PyPI:
```
pdm add package
```
To add a dependency from a local file:
```
pdm add path/to/package
```

Examples:
```
pdm add matplotlib
pdm add ~/glasgow/software
```

To add a dependency to a group:
```
pdm add -G group dependency
```

Example:
```
pdm add -G gui pyqtgraph
```

## Running tests
OBI tests run with [unittest](https://docs.python.org/3/library/unittest.html).

To run all tests:
```
pdm run test
```

To run a specific test:
```
pdm run test tests.commands.test_structs -k test_from_resolution
```
This runs the test `DACCodeRangeTest.test_from_resolution()` in `/software/tests/commands/test_structs`.

## Waveform simulations
Gateware simulations, located in `software/tests/gateware/test_open_beam_interface.py`, produce `.vcd` files. I have tried and would recommend the following VCD viewers:
- [GTKWave](https://gtkwave.sourceforge.net) is the most full featured free and open source VCD viewer.
    - I used [randomplum's Homebrew tap](https://github.com/gtkwave/gtkwave/issues/250#issuecomment-1739998393) to get a version built with gtk3 so that it looks better on MacOS
- [WaveTrace](https://www.wavetrace.io) is a VSCode plugin. The free version lets you view 8 waveforms, for a one time payment of $15 you can get unlimited waveforms.
- [Surfer](https://surfer-project.org) is a new open source VCD viewer, you can use it directly in the browser.

Useful GTKWave configurations for viewing simulation outputs are stored in `software/tests/gtkwave`.