Introduction

Introduction#

sphinx-peakrdl is an extension that integrates PeakRDL’s register map documentation capabilities into your Sphinx-Doc project.

Using this extension, you can:

  • Automatically generate PeakRDL-HTML output from within the Sphinx build flow

  • Create cross-reference links to register map elements from your reStructuredText document.

  • Insert register reference content inline into your document (Useful if you want to generate offline PDF docs)

Get Started#

Install#

Install from PyPi using pip

python3 -m pip install sphinx-peakrdl

Configure#

Enable the extension in your Sphinx-Doc conf.py:

conf.py#
extensions = [
    "sphinx_peakrdl",
]

Provide the extension a list of PeakRDL input files to process:

conf.py#
peakrdl_input_files = [
    "path/to/turboencabulator.rdl",
    "path/to/ethernet_mac.rdl",
    "path/to/thingamabob_top.rdl",
]

Start cross-referencing!#

Cross-reference your documentation to automatically-generated PeakRDL-HTML pages.

This is really useful when writing software guides or other reference pages. For example:

Thingamabob startup sequence:

1. Configure the :rdl:ref:`my_soc.thingamabob.ctrl` register to the desired settings.
2. Enable the device by setting :rdl:ref:`my_soc.thingamabob.ctrl.en` to ``1``.
3. Check :rdl:ref:`my_soc.thingamabob.status` for errors.

Results in the following output:

Thingamabob startup sequence:

  1. Configure the my_soc.thingamabob.ctrl register to the desired settings.

  2. Enable the device by setting my_soc.thingamabob.ctrl.en to 1.

  3. Check my_soc.thingamabob.status for errors.