Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ the git log and on [PyPI](https://pypi.org/project/bust/#history).
### Added
- `bust.generate_files` returns every output file as `{path: content}`, without writing to disk or running `pdflatex`. The command line writes that result.
- `doc/<module>.html`, the documentation as one self-contained HTML page with inline SVG bit diagrams, links between the register list and the registers, a sidebar and a print stylesheet.
- `doc/<module>.md`, the documentation as Markdown, with the register list and a bits table per register, readable on GitHub.
- `doc/<module>.md`, the documentation as Markdown, with the register list and a bits table per register, readable on GitHub, with the table columns lined up in the source.
- The documentation hosts the register map JSON Schema at https://bust.readthedocs.io/en/stable/register-map.schema.json. A register map may point to it with a `"$schema"` key, which gives completion, hover text and errors in editors with JSON Schema support. The editor adds the key to new register maps.
- `bust.bundle_zip` turns the result of `generate_files` into one zip, in the folder layout the CLI writes, with a `README.md` that lists what each file is.
- `bust.bundle_zip` turns the result of `generate_files` into one zip, in the folder layout the CLI writes, with a `README.md` that lists what each file is and names the bust version and time.
- bust runs under Pyodide in the browser. Getting started lists the dependencies to install there, and CI checks that the wheel generates every example under Pyodide as it does under CPython.

### Changed
Expand Down
7 changes: 4 additions & 3 deletions bust/bundle.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@
import zipfile
from typing import Iterable, Mapping, Union

from bust._version import __VERSION__
from bust.jinja_utils.environment import generated_by
from bust.jinja_utils.filters import align_markdown_tables

README_NAME = "README.md"

Expand Down Expand Up @@ -51,10 +52,10 @@ def describe_file(path: str) -> str:
def build_readme(paths: Iterable[str]) -> str:
"""Return a README.md that lists each of `paths` with what it is."""
rows = "".join(f"| `{path}` | {describe_file(path)} |\n" for path in sorted(paths))
return (
return align_markdown_tables(
"# Generated files\n"
"\n"
f"Generated by bust {__VERSION__}.\n"
f"{generated_by()}.\n"
"\n"
"| File | What it is |\n"
"| --- | --- |\n"
Expand Down
5 changes: 4 additions & 1 deletion bust/generators/documentation_generator.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
register_list,
)
from bust.jinja_utils.environment import render_template
from bust.jinja_utils.filters import align_markdown_tables

# An estimate of a character's width at the 11px font of the names, enough to
# tell whether a name fits across its box or must be turned on its side.
Expand Down Expand Up @@ -177,4 +178,6 @@ def generate_markdown_documentation(self, test_version=None):
Returns:
Markdown document as string.
"""
return self._render_template("markdown/documentation.j2", test_version)
return align_markdown_tables(
self._render_template("markdown/documentation.j2", test_version)
)
66 changes: 66 additions & 0 deletions bust/jinja_utils/filters.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
- utf8tolatex: Convert UTF-8 text to LaTeX-safe encoding.
- utf8tohtml: Escape text for HTML, with `code` spans as <code>.
- markdown_cell: Escape text for one cell of a Markdown table.
- align_markdown_tables: Pad the cells of every Markdown table into columns.

Copyright (c) 2025 Ola Groettvik
Licensed under the Apache License, Version 2.0. See the LICENSE file for details.
Expand Down Expand Up @@ -175,3 +176,68 @@ def markdown_cell(text):
for i, part in enumerate(parts)
)
return " ".join(escaped.split())


_MARKDOWN_DELIMITER_CELL = re.compile(r":?-+:?")


def _markdown_row_cells(line):
"""The cells of a table row. A backslash escapes the character after it, so
an escaped | stays in its cell."""
cells, cell, chars = [], "", iter(line.strip()[1:])
for char in chars:
if char == "\\":
cell += char + next(chars, "")
elif char == "|":
cells.append(cell.strip())
cell = ""
else:
cell += char
return cells


def _aligned_markdown_table(rows):
delimiter = rows[1]
widths = [
max(3, *(len(row[column]) for row in rows if row is not delimiter))
for column in range(len(delimiter))
]
lines = []
for row in rows:
cells = []
for cell, width, spec in zip(row, widths, delimiter):
if row is delimiter:
left = ":" if spec.startswith(":") else "-"
right = ":" if spec.endswith(":") else "-"
cells.append(left + "-" * (width - 2) + right)
elif spec.endswith(":") and not spec.startswith(":"):
cells.append(cell.rjust(width))
else:
cells.append(cell.ljust(width))
lines.append("| " + " | ".join(cells) + " |")
return lines


def align_markdown_tables(text: str) -> str:
"""Pad the cells of every Markdown table so its columns line up in the
source. A table is a run of lines that start with | and whose second line
is the delimiter row. Rendered Markdown looks the same."""
lines = text.split("\n")
aligned, start = [], 0
while start < len(lines):
end = start
while end < len(lines) and lines[end].lstrip().startswith("|"):
end += 1
rows = [_markdown_row_cells(line) for line in lines[start:end]]
is_table = (
len(rows) >= 2
and all(_MARKDOWN_DELIMITER_CELL.fullmatch(cell) for cell in rows[1])
and all(len(row) == len(rows[1]) for row in rows)
)
if is_table:
aligned.extend(_aligned_markdown_table(rows))
start = end
else:
aligned.append(lines[start])
start += 1
return "\n".join(aligned)
150 changes: 75 additions & 75 deletions example/example_axi/doc/example_axi.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,22 @@ An example module that contain all the register types that are currently support

## Register list

| # | Name | SW/HW | Address | Type | Width | Reset |
|--:|------|-------|---------|------|------:|-------|
| 0 | [reg0](#reg0) | RW/R | `0x00000000` | BIT | 1 | `0x0` |
| 1 | [reg1](#reg1) | RW/R | `0x00000004` | BIT | 1 | `0x1` |
| 2 | [reg2](#reg2) | RO/W | `0x00000008` | BIT | 1 | `0x0` |
| 3 | [reg3](#reg3) | RW/R | `0x0000000C` | VECTOR | 8 | `0x3` |
| 4 | [reg4](#reg4) | RO/W | `0x00000010` | VECTOR | 14 | `0x0` |
| 5 | [reg5](#reg5) | RW/R | `0x00000014` | DEFAULT | 32 | `0xFFFFFFFF` |
| 6 | [reg6](#reg6) | RO/W | `0x00000018` | DEFAULT | 32 | `0x0` |
| 7 | [reg7](#reg7) | RW/R | `0x0000001C` | FIELDS | 21 | `0xAD7` |
| 8 | [reg8](#reg8) | RO/W | `0x00000020` | FIELDS | 24 | `0x0` |
| 9 | [reg9](#reg9) | WO/R | `0x00000024` | BIT | 1 | `0x1` |
| 10 | [reg10](#reg10) | WO/R | `0x00000028` | VECTOR | 4 | `0xA` |
| 11 | [reg11](#reg11) | WO/R | `0x0000002C` | FIELDS | 16 | `0x3` |
| 12 | [regmap_hash](#regmap_hash) | RO/NA | `0x00000030` | HASH | 32 | `0xCF519FC` |
| 13 | [regmap_version](#regmap_version) | RO/NA | `0x00000034` | VERSION | 32 | `0x10000` |
| # | Name | SW/HW | Address | Type | Width | Reset |
| --: | --------------------------------- | ----- | ------------ | ------- | ----: | ------------ |
| 0 | [reg0](#reg0) | RW/R | `0x00000000` | BIT | 1 | `0x0` |
| 1 | [reg1](#reg1) | RW/R | `0x00000004` | BIT | 1 | `0x1` |
| 2 | [reg2](#reg2) | RO/W | `0x00000008` | BIT | 1 | `0x0` |
| 3 | [reg3](#reg3) | RW/R | `0x0000000C` | VECTOR | 8 | `0x3` |
| 4 | [reg4](#reg4) | RO/W | `0x00000010` | VECTOR | 14 | `0x0` |
| 5 | [reg5](#reg5) | RW/R | `0x00000014` | DEFAULT | 32 | `0xFFFFFFFF` |
| 6 | [reg6](#reg6) | RO/W | `0x00000018` | DEFAULT | 32 | `0x0` |
| 7 | [reg7](#reg7) | RW/R | `0x0000001C` | FIELDS | 21 | `0xAD7` |
| 8 | [reg8](#reg8) | RO/W | `0x00000020` | FIELDS | 24 | `0x0` |
| 9 | [reg9](#reg9) | WO/R | `0x00000024` | BIT | 1 | `0x1` |
| 10 | [reg10](#reg10) | WO/R | `0x00000028` | VECTOR | 4 | `0xA` |
| 11 | [reg11](#reg11) | WO/R | `0x0000002C` | FIELDS | 16 | `0x3` |
| 12 | [regmap_hash](#regmap_hash) | RO/NA | `0x00000030` | HASH | 32 | `0xCF519FC` |
| 13 | [regmap_version](#regmap_version) | RO/NA | `0x00000034` | VERSION | 32 | `0x10000` |

## Registers

Expand All @@ -31,153 +31,153 @@ Address `0x00000000`, RW/R, reset `0x0`.

RW std_logic register that resets to 0x0

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:1 | reserved | | | | Read as 0, writes have no effect. |
| 0 | reg0 | rw | r | `0x0` | |
| Bits | Name | SW | HW | Reset | Description |
| ---- | -------- | --- | --- | ----- | --------------------------------- |
| 31:1 | reserved | | | | Read as 0, writes have no effect. |
| 0 | reg0 | rw | r | `0x0` | |

### reg1

Address `0x00000004`, RW/R, reset `0x1`.

RW std_logic register that resets to 0x1

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:1 | reserved | | | | Read as 0, writes have no effect. |
| 0 | reg1 | rw | r | `0x1` | |
| Bits | Name | SW | HW | Reset | Description |
| ---- | -------- | --- | --- | ----- | --------------------------------- |
| 31:1 | reserved | | | | Read as 0, writes have no effect. |
| 0 | reg1 | rw | r | `0x1` | |

### reg2

Address `0x00000008`, RO/W, reset `0x0`.

RO std_logic register

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:1 | reserved | | | | Read as 0, writes have no effect. |
| 0 | reg2 | ro | w | `0x0` | |
| Bits | Name | SW | HW | Reset | Description |
| ---- | -------- | --- | --- | ----- | --------------------------------- |
| 31:1 | reserved | | | | Read as 0, writes have no effect. |
| 0 | reg2 | ro | w | `0x0` | |

### reg3

Address `0x0000000C`, RW/R, reset `0x3`.

RW std_logic_vector\[7:0\] register that resets to 0x3

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:8 | reserved | | | | Read as 0, writes have no effect. |
| 7:0 | reg3 | rw | r | `0x3` | |
| Bits | Name | SW | HW | Reset | Description |
| ---- | -------- | --- | --- | ----- | --------------------------------- |
| 31:8 | reserved | | | | Read as 0, writes have no effect. |
| 7:0 | reg3 | rw | r | `0x3` | |

### reg4

Address `0x00000010`, RO/W, reset `0x0`.

RO std_logic_vector\[13:0\]

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:14 | reserved | | | | Read as 0, writes have no effect. |
| 13:0 | reg4 | ro | w | `0x0` | |
| Bits | Name | SW | HW | Reset | Description |
| ----- | -------- | --- | --- | ----- | --------------------------------- |
| 31:14 | reserved | | | | Read as 0, writes have no effect. |
| 13:0 | reg4 | ro | w | `0x0` | |

### reg5

Address `0x00000014`, RW/R, reset `0xFFFFFFFF`.

Default RW register that resets to 0xFFFFFFFF

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:0 | reg5 | rw | r | `0xFFFFFFFF` | |
| Bits | Name | SW | HW | Reset | Description |
| ---- | ---- | --- | --- | ------------ | ----------- |
| 31:0 | reg5 | rw | r | `0xFFFFFFFF` | |

### reg6

Address `0x00000018`, RO/W, reset `0x0`.

Default RO register

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:0 | reg6 | ro | w | `0x0` | |
| Bits | Name | SW | HW | Reset | Description |
| ---- | ---- | --- | --- | ----- | ----------- |
| 31:0 | reg6 | ro | w | `0x0` | |

### reg7

Address `0x0000001C`, RW/R, reset `0xAD7`.

RW register that have multiple fields

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:21 | reserved | | | | Read as 0, writes have no effect. |
| 20:6 | field3 | rw | r | `0x2B` | std_logic_vector\[14:0\] that resets to 0x2b |
| 5 | field2 | rw | r | `0x0` | std_logic that resets to 0x1 |
| 4:1 | field1 | rw | r | `0xB` | std_logic_vector\[3:0\] that resets to 0xb is not a valid reset value |
| 0 | field0 | rw | r | `0x1` | std_logic that resets to 0x1 |
| Bits | Name | SW | HW | Reset | Description |
| ----- | -------- | --- | --- | ------ | --------------------------------------------------------------------- |
| 31:21 | reserved | | | | Read as 0, writes have no effect. |
| 20:6 | field3 | rw | r | `0x2B` | std_logic_vector\[14:0\] that resets to 0x2b |
| 5 | field2 | rw | r | `0x0` | std_logic that resets to 0x1 |
| 4:1 | field1 | rw | r | `0xB` | std_logic_vector\[3:0\] that resets to 0xb is not a valid reset value |
| 0 | field0 | rw | r | `0x1` | std_logic that resets to 0x1 |

### reg8

Address `0x00000020`, RO/W, reset `0x0`.

RO register with multiple types of fields

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:24 | reserved | | | | Read as 0, writes have no effect. |
| 23:21 | field3 | ro | w | `0x0` | std_logic_vector\[2:0\] field |
| 20 | field2 | ro | w | `0x0` | std_logic field |
| 19:1 | field1 | ro | w | `0x0` | std_logic_vector\[18:0\] field |
| 0 | field0 | ro | w | `0x0` | std_logic field |
| Bits | Name | SW | HW | Reset | Description |
| ----- | -------- | --- | --- | ----- | --------------------------------- |
| 31:24 | reserved | | | | Read as 0, writes have no effect. |
| 23:21 | field3 | ro | w | `0x0` | std_logic_vector\[2:0\] field |
| 20 | field2 | ro | w | `0x0` | std_logic field |
| 19:1 | field1 | ro | w | `0x0` | std_logic_vector\[18:0\] field |
| 0 | field0 | ro | w | `0x0` | std_logic field |

### reg9

Address `0x00000024`, WO/R, reset `0x1`.

PULSE std_logic register that resets to 0x1

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:1 | reserved | | | | Read as 0, writes have no effect. |
| 0 | reg9 | wo | r | `0x1` | singlepulse. |
| Bits | Name | SW | HW | Reset | Description |
| ---- | -------- | --- | --- | ----- | --------------------------------- |
| 31:1 | reserved | | | | Read as 0, writes have no effect. |
| 0 | reg9 | wo | r | `0x1` | singlepulse. |

### reg10

Address `0x00000028`, WO/R, reset `0xA`.

PULSE std_logic_vector\[3:0\] register that resets to 0xA

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:4 | reserved | | | | Read as 0, writes have no effect. |
| 3:0 | reg10 | wo | r | `0xA` | singlepulse. |
| Bits | Name | SW | HW | Reset | Description |
| ---- | -------- | --- | --- | ----- | --------------------------------- |
| 31:4 | reserved | | | | Read as 0, writes have no effect. |
| 3:0 | reg10 | wo | r | `0xA` | singlepulse. |

### reg11

Address `0x0000002C`, WO/R, reset `0x3`.

PULSE register with two fields

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:16 | reserved | | | | Read as 0, writes have no effect. |
| 15 | field1 | wo | r | `0x0` | std_logic field that resets to 0x0 singlepulse. |
| 14:0 | field0 | wo | r | `0x3` | std_logic_vector\[14:0\] field that resets to 0x3 singlepulse. |
| Bits | Name | SW | HW | Reset | Description |
| ----- | -------- | --- | --- | ----- | -------------------------------------------------------------- |
| 31:16 | reserved | | | | Read as 0, writes have no effect. |
| 15 | field1 | wo | r | `0x0` | std_logic field that resets to 0x0 singlepulse. |
| 14:0 | field0 | wo | r | `0x3` | std_logic_vector\[14:0\] field that resets to 0x3 singlepulse. |

### regmap_hash

Address `0x00000030`, RO/NA, reset `0xCF519FC`.

Hash of the register map, to compare with EXAMPLE_AXI_REGMAP_HASH in the header

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:0 | regmap_hash | ro | na | `0xCF519FC` | |
| Bits | Name | SW | HW | Reset | Description |
| ---- | ----------- | --- | --- | ----------- | ----------- |
| 31:0 | regmap_hash | ro | na | `0xCF519FC` | |

### regmap_version

Address `0x00000034`, RO/NA, reset `0x10000`.

Version of the register map, 1.0 as 0x00010000

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
| 31:0 | regmap_version | ro | na | `0x10000` | |
| Bits | Name | SW | HW | Reset | Description |
| ---- | -------------- | --- | --- | --------- | ----------- |
| 31:0 | regmap_version | ro | na | `0x10000` | |
Loading
Loading