Developing OBI

Editing the documentation

OBI documentation is built with Sphinx and the MyST Markdown parser. This configuration was chosen to combine the advanced autodocumentation features of Sphinx with the lower friction of writing in Markdown.

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 to install OBI in a virtual environment, so all installs are local and editable. After installing 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.

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 is the most full featured free and open source VCD viewer.

  • WaveTrace 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 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.