HTML Documentation Generator for SystemRDL

2.12.2 · active · verified Thu Apr 16

PeakRDL-html is a plugin for the PeakRDL parser that generates interactive HTML documentation for SystemRDL-based register models. It processes RDL source files to produce browsable web pages detailing register maps, fields, and properties. The current version is 2.12.2, and it maintains an active development cycle with regular updates addressing bug fixes and new features.

Common errors

```
ModuleNotFoundError: No module named 'peakrdl.html'
```
cause This error occurs when trying to import from the deprecated `peakrdl.html` namespace package, which was removed in version 2.10.0.

fix The `peakrdl.html` namespace is no longer available for direct import. If you intended to use the HTML backend, the standard method is via the `peakrdl --html` command-line tool. If you need programmatic access, look for specific classes or functions directly under `peakrdl_html` (e.g., `from peakrdl_html.backend import HtmlBackend`).
```
Error: peakrdl-html requires Python 3.7 or greater
```
cause You are attempting to install or run peakrdl-html version 2.11.0 or newer with an unsupported Python version (3.5 or 3.6).

fix Upgrade your Python environment to version 3.7 or higher to use peakrdl-html versions 2.11.0+.

Warnings

breaking Python 3.5 and 3.6 support was dropped in v2.11.0. Users on these older Python versions will encounter 'Unsupported Python version' errors or installation failures.
Fix: Upgrade to Python 3.7 or newer. Python 3.7 is the minimum requirement for versions 2.11.0 and above.
deprecated Inline math tags using escaped parentheses `\(...)\` were deprecated in v2.11.0 and will be removed in v3.0. These should be replaced with dollar-style `$...$` inline math tags.
Fix: Update your SystemRDL source files to use `$...$` for inline math expressions instead of `\(...)\`.
breaking The `peakrdl.html` namespace package was removed in v2.10.0. Any direct imports from this path will now fail.
Fix: If you were programmatically interacting with `peakrdl.html` components, you may need to adjust imports. For typical usage, rely on the `peakrdl --html` command-line interface, as direct Python API usage for generation is less common.

Install

pip install peakrdl-html Install latest version

Imports

HtmlBackend
```
from peakrdl_html.backend import HtmlBackend
```
While programmatic imports are possible (e.g., for custom integrations), the primary and recommended way for end-users to generate documentation is via the 'peakrdl --html' command-line interface.

Quickstart

This quickstart demonstrates how to create a minimal SystemRDL file and then use the `peakrdl` command-line tool with the `--html` flag to generate documentation. The output HTML files will be placed in the specified 'docs' directory. Ensure `peakrdl-html` is installed, which will also pull in `peakrdl`.

echo 'addrmap my_block { reg my_reg { field { hw=w; sw=r; } my_field[32]; } @0x0; };' > example.rdl
pip install peakrdl-html
peakrdl --html -o docs example.rdl
ls docs/index.html

view raw JSON →