From 6a291e4d069fb56304e431f1870b5a1a783478f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ola=20Gr=C3=B8ttvik?= Date: Fri, 30 Oct 2026 08:00:07 +0000 Subject: [PATCH 1/2] Line up Markdown table columns and date the zip README --- CHANGELOG.md | 4 +- bust/bundle.py | 7 +- bust/generators/documentation_generator.py | 5 +- bust/jinja_utils/filters.py | 66 +++++++++ example/example_axi/doc/example_axi.md | 150 ++++++++++----------- example/example_ipbus/doc/example_ipbus.md | 134 +++++++++--------- example/example_prototype/doc/prototype.md | 148 ++++++++++---------- tests/test_bundle.py | 9 +- tests/test_cli.py | 3 +- tests/test_markdown.py | 19 ++- tests/test_reserved_fields.py | 9 ++ 11 files changed, 328 insertions(+), 226 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 21d7b11..dfe34ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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/.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/.md`, the documentation as Markdown, with the register list and a bits table per register, readable on GitHub. +- `doc/.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 diff --git a/bust/bundle.py b/bust/bundle.py index 9f31a54..a9ede50 100644 --- a/bust/bundle.py +++ b/bust/bundle.py @@ -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" @@ -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" diff --git a/bust/generators/documentation_generator.py b/bust/generators/documentation_generator.py index ffe0a7f..c0e259f 100644 --- a/bust/generators/documentation_generator.py +++ b/bust/generators/documentation_generator.py @@ -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. @@ -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) + ) diff --git a/bust/jinja_utils/filters.py b/bust/jinja_utils/filters.py index 1b12841..2980f50 100644 --- a/bust/jinja_utils/filters.py +++ b/bust/jinja_utils/filters.py @@ -10,6 +10,7 @@ - utf8tolatex: Convert UTF-8 text to LaTeX-safe encoding. - utf8tohtml: Escape text for HTML, with `code` spans as . - 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. @@ -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): + """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) diff --git a/example/example_axi/doc/example_axi.md b/example/example_axi/doc/example_axi.md index 5e79954..8da763c 100644 --- a/example/example_axi/doc/example_axi.md +++ b/example/example_axi/doc/example_axi.md @@ -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 @@ -31,10 +31,10 @@ 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 @@ -42,10 +42,10 @@ 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 @@ -53,10 +53,10 @@ 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 @@ -64,10 +64,10 @@ 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 @@ -75,10 +75,10 @@ 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 @@ -86,9 +86,9 @@ 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 @@ -96,9 +96,9 @@ 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 @@ -106,13 +106,13 @@ 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 @@ -120,13 +120,13 @@ 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 @@ -134,10 +134,10 @@ 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 @@ -145,10 +145,10 @@ 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 @@ -156,11 +156,11 @@ 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 @@ -168,9 +168,9 @@ 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 @@ -178,6 +178,6 @@ 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` | | diff --git a/example/example_ipbus/doc/example_ipbus.md b/example/example_ipbus/doc/example_ipbus.md index 82e5d52..3a8c421 100644 --- a/example/example_ipbus/doc/example_ipbus.md +++ b/example/example_ipbus/doc/example_ipbus.md @@ -6,20 +6,20 @@ 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` | +| # | 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` | ## Registers @@ -29,10 +29,10 @@ 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 @@ -40,10 +40,10 @@ 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 @@ -51,10 +51,10 @@ 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 @@ -62,10 +62,10 @@ 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 @@ -73,10 +73,10 @@ 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 @@ -84,9 +84,9 @@ 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 @@ -94,9 +94,9 @@ 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 @@ -104,13 +104,13 @@ 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 @@ -118,13 +118,13 @@ 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 @@ -132,10 +132,10 @@ 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 @@ -143,10 +143,10 @@ 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 @@ -154,8 +154,8 @@ 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. | diff --git a/example/example_prototype/doc/prototype.md b/example/example_prototype/doc/prototype.md index ed626d5..ef90e8b 100644 --- a/example/example_prototype/doc/prototype.md +++ b/example/example_prototype/doc/prototype.md @@ -6,20 +6,20 @@ Comprehensive example exercising every v1 access mode, mirroring the prototype d ## Register list -| # | Name | SW/HW | Address | Type | Width | Reset | -|--:|------|-------|---------|------|------:|-------| -| 0 | [reg0](#reg0) | RW/R | `0x00000000` | FIELDS | 3 | `0x0` | -| 1 | [reg1](#reg1) | RO/W | `0x00000004` | FIELDS | 6 | `0x0` | -| 2 | [reg2](#reg2) | WO/R | `0x00000008` | FIELDS | 1 | `0x0` | -| 3 | [reg3](#reg3) | RW/NA | `0x0000000C` | FIELDS | 8 | `0x0` | -| 4 | [reg4](#reg4) | RW/RW | `0x00000010` | FIELDS | 9 | `0x0` | -| 5 | [reg5](#reg5) | RW/R | `0x00000014` | FIELDS | 8 | `0x0` | -| 6 | [reg6](#reg6) | RW/R | `0x00000018` | FIELDS | 12 | `0xF0` | -| 7 | [reg7](#reg7) | RW/R | `0x0000001C` | FIELDS | 12 | `0xF0` | -| 8 | [reg8](#reg8) | RW/R | `0x00000020` | FIELDS | 8 | `0xF` | -| 9 | [reg9](#reg9) | RW/R | `0x00000024` | FIELDS | 8 | `0x0` | -| 10 | [reg10](#reg10) | RW/R | `0x00000028` | FIELDS | 4 | `0x0` | -| 11 | [reg11](#reg11) | RW/R | `0x0000002C` | FIELDS | 2 | `0x0` | +| # | Name | SW/HW | Address | Type | Width | Reset | +| --: | --------------- | ----- | ------------ | ------ | ----: | ------ | +| 0 | [reg0](#reg0) | RW/R | `0x00000000` | FIELDS | 3 | `0x0` | +| 1 | [reg1](#reg1) | RO/W | `0x00000004` | FIELDS | 6 | `0x0` | +| 2 | [reg2](#reg2) | WO/R | `0x00000008` | FIELDS | 1 | `0x0` | +| 3 | [reg3](#reg3) | RW/NA | `0x0000000C` | FIELDS | 8 | `0x0` | +| 4 | [reg4](#reg4) | RW/RW | `0x00000010` | FIELDS | 9 | `0x0` | +| 5 | [reg5](#reg5) | RW/R | `0x00000014` | FIELDS | 8 | `0x0` | +| 6 | [reg6](#reg6) | RW/R | `0x00000018` | FIELDS | 12 | `0xF0` | +| 7 | [reg7](#reg7) | RW/R | `0x0000001C` | FIELDS | 12 | `0xF0` | +| 8 | [reg8](#reg8) | RW/R | `0x00000020` | FIELDS | 8 | `0xF` | +| 9 | [reg9](#reg9) | RW/R | `0x00000024` | FIELDS | 8 | `0x0` | +| 10 | [reg10](#reg10) | RW/R | `0x00000028` | FIELDS | 4 | `0x0` | +| 11 | [reg11](#reg11) | RW/R | `0x0000002C` | FIELDS | 2 | `0x0` | ## Registers @@ -29,11 +29,11 @@ Address `0x00000000`, RW/R, reset `0x0`. Plain rw storage, hardware reads back. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:3 | reserved | | | | Read as 0, writes have no effect. | -| 2:1 | field1 | rw | r | `0x0` | | -| 0 | field0 | rw | r | `0x0` | | +| Bits | Name | SW | HW | Reset | Description | +| ---- | -------- | --- | --- | ----- | --------------------------------- | +| 31:3 | reserved | | | | Read as 0, writes have no effect. | +| 2:1 | field1 | rw | r | `0x0` | | +| 0 | field0 | rw | r | `0x0` | | ### reg1 @@ -41,12 +41,12 @@ Address `0x00000004`, RO/W, reset `0x0`. Hardware-driven status, software read-only. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:6 | reserved | | | | Read as 0, writes have no effect. | -| 5 | field2 | ro | w | `0x0` | Modifiers: wel. | -| 4 | field1 | ro | w | `0x0` | | -| 3:0 | field0 | ro | w | `0x0` | Modifiers: we. | +| Bits | Name | SW | HW | Reset | Description | +| ---- | -------- | --- | --- | ----- | --------------------------------- | +| 31:6 | reserved | | | | Read as 0, writes have no effect. | +| 5 | field2 | ro | w | `0x0` | Modifiers: wel. | +| 4 | field1 | ro | w | `0x0` | | +| 3:0 | field0 | ro | w | `0x0` | Modifiers: we. | ### reg2 @@ -54,10 +54,10 @@ Address `0x00000008`, WO/R, reset `0x0`. Write-only command field. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:1 | reserved | | | | Read as 0, writes have no effect. | -| 0 | field0 | wo | r | `0x0` | | +| Bits | Name | SW | HW | Reset | Description | +| ---- | -------- | --- | --- | ----- | --------------------------------- | +| 31:1 | reserved | | | | Read as 0, writes have no effect. | +| 0 | field0 | wo | r | `0x0` | | ### reg3 @@ -65,10 +65,10 @@ Address `0x0000000C`, RW/NA, reset `0x0`. Software-only scratch register. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:8 | reserved | | | | Read as 0, writes have no effect. | -| 7:0 | field0 | rw | na | `0x0` | | +| Bits | Name | SW | HW | Reset | Description | +| ---- | -------- | --- | --- | ----- | --------------------------------- | +| 31:8 | reserved | | | | Read as 0, writes have no effect. | +| 7:0 | field0 | rw | na | `0x0` | | ### reg4 @@ -76,12 +76,12 @@ Address `0x00000010`, RW/RW, reset `0x0`. Hardware write-enable and hardware set/clear. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:9 | reserved | | | | Read as 0, writes have no effect. | -| 8 | field1 | rw | r | `0x0` | Modifiers: hwset, hwclr. | -| 7:4 | reserved | | | | Read as 0, writes have no effect. | -| 3:0 | field0 | rw | rw | `0x0` | Modifiers: we. | +| Bits | Name | SW | HW | Reset | Description | +| ---- | -------- | --- | --- | ----- | --------------------------------- | +| 31:9 | reserved | | | | Read as 0, writes have no effect. | +| 8 | field1 | rw | r | `0x0` | Modifiers: hwset, hwclr. | +| 7:4 | reserved | | | | Read as 0, writes have no effect. | +| 3:0 | field0 | rw | rw | `0x0` | Modifiers: we. | ### reg5 @@ -89,11 +89,11 @@ Address `0x00000014`, RW/R, reset `0x0`. Read side effects. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:8 | reserved | | | | Read as 0, writes have no effect. | -| 7:4 | field1 | rw | r | `0x0` | onread: rset. | -| 3:0 | field0 | rw | r | `0x0` | onread: rclr. | +| Bits | Name | SW | HW | Reset | Description | +| ---- | -------- | --- | --- | ----- | --------------------------------- | +| 31:8 | reserved | | | | Read as 0, writes have no effect. | +| 7:4 | field1 | rw | r | `0x0` | onread: rset. | +| 3:0 | field0 | rw | r | `0x0` | onread: rclr. | ### reg6 @@ -101,12 +101,12 @@ Address `0x00000018`, RW/R, reset `0xF0`. Write-1 onwrite effects. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:12 | reserved | | | | Read as 0, writes have no effect. | -| 11:8 | field2 | rw | r | `0x0` | onwrite: wot. | -| 7:4 | field1 | rw | r | `0xF` | onwrite: woclr. | -| 3:0 | field0 | rw | r | `0x0` | onwrite: woset. | +| Bits | Name | SW | HW | Reset | Description | +| ----- | -------- | --- | --- | ----- | --------------------------------- | +| 31:12 | reserved | | | | Read as 0, writes have no effect. | +| 11:8 | field2 | rw | r | `0x0` | onwrite: wot. | +| 7:4 | field1 | rw | r | `0xF` | onwrite: woclr. | +| 3:0 | field0 | rw | r | `0x0` | onwrite: woset. | ### reg7 @@ -114,12 +114,12 @@ Address `0x0000001C`, RW/R, reset `0xF0`. Write-0 onwrite effects. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:12 | reserved | | | | Read as 0, writes have no effect. | -| 11:8 | field2 | rw | r | `0x0` | onwrite: wzt. | -| 7:4 | field1 | rw | r | `0xF` | onwrite: wzc. | -| 3:0 | field0 | rw | r | `0x0` | onwrite: wzs. | +| Bits | Name | SW | HW | Reset | Description | +| ----- | -------- | --- | --- | ----- | --------------------------------- | +| 31:12 | reserved | | | | Read as 0, writes have no effect. | +| 11:8 | field2 | rw | r | `0x0` | onwrite: wzt. | +| 7:4 | field1 | rw | r | `0xF` | onwrite: wzc. | +| 3:0 | field0 | rw | r | `0x0` | onwrite: wzs. | ### reg8 @@ -127,11 +127,11 @@ Address `0x00000020`, RW/R, reset `0xF`. Whole-field onwrite effects. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:8 | reserved | | | | Read as 0, writes have no effect. | -| 7:4 | field1 | rw | r | `0x0` | onwrite: wset. | -| 3:0 | field0 | rw | r | `0xF` | onwrite: wclr. | +| Bits | Name | SW | HW | Reset | Description | +| ---- | -------- | --- | --- | ----- | --------------------------------- | +| 31:8 | reserved | | | | Read as 0, writes have no effect. | +| 7:4 | field1 | rw | r | `0x0` | onwrite: wset. | +| 3:0 | field0 | rw | r | `0xF` | onwrite: wclr. | ### reg9 @@ -139,11 +139,11 @@ Address `0x00000024`, RW/R, reset `0x0`. Software-access pulses. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:8 | reserved | | | | Read as 0, writes have no effect. | -| 7:4 | field1 | rw | r | `0x0` | Modifiers: swacc. | -| 3:0 | field0 | rw | r | `0x0` | Modifiers: swmod. | +| Bits | Name | SW | HW | Reset | Description | +| ---- | -------- | --- | --- | ----- | --------------------------------- | +| 31:8 | reserved | | | | Read as 0, writes have no effect. | +| 7:4 | field1 | rw | r | `0x0` | Modifiers: swacc. | +| 3:0 | field0 | rw | r | `0x0` | Modifiers: swmod. | ### reg10 @@ -151,10 +151,10 @@ Address `0x00000028`, RW/R, reset `0x0`. Single-cycle pulse on software write. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:4 | reserved | | | | Read as 0, writes have no effect. | -| 3:0 | field0 | rw | r | `0x0` | singlepulse. | +| Bits | Name | SW | HW | Reset | Description | +| ---- | -------- | --- | --- | ----- | --------------------------------- | +| 31:4 | reserved | | | | Read as 0, writes have no effect. | +| 3:0 | field0 | rw | r | `0x0` | singlepulse. | ### reg11 @@ -162,7 +162,7 @@ Address `0x0000002C`, RW/R, reset `0x0`. Enumerated field. -| Bits | Name | SW | HW | Reset | Description | -|------|------|----|----|-------|-------------| -| 31:2 | reserved | | | | Read as 0, writes have no effect. | -| 1:0 | field0 | rw | r | `0x0` | Values: STATE0=0, STATE1=1, STATE2=2, STATE3=3. | +| Bits | Name | SW | HW | Reset | Description | +| ---- | -------- | --- | --- | ----- | ----------------------------------------------- | +| 31:2 | reserved | | | | Read as 0, writes have no effect. | +| 1:0 | field0 | rw | r | `0x0` | Values: STATE0=0, STATE1=1, STATE2=2, STATE3=3. | diff --git a/tests/test_bundle.py b/tests/test_bundle.py index 85bc7c2..5d05731 100644 --- a/tests/test_bundle.py +++ b/tests/test_bundle.py @@ -34,7 +34,7 @@ def test_zip_of_generate_files_describes_every_file(example): for path, content in files.items(): assert entries[path] == content.encode("utf-8") assert describe_file(path), path - assert f"| `{path}` |" in readme + assert f"| `{path}` " in readme def test_zip_stores_bytes_unchanged(): @@ -71,7 +71,12 @@ def test_describe_file(path, expected): def test_readme_lists_unknown_files_without_description(): - assert "| `m/notes.txt` | |" in build_readme(["m/notes.txt"]) + assert "| `m/notes.txt` | |" in build_readme(["m/notes.txt"]) + + +def test_readme_names_bust_version_and_time(): + assert "Generated by bust v" in build_readme([]) + assert "1970-01-01 00:00" in build_readme([]) def test_readme_name_is_reserved(): diff --git a/tests/test_cli.py b/tests/test_cli.py index 743c327..f9b3b27 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -2,6 +2,7 @@ import json import os +import re import subprocess import sys @@ -199,7 +200,7 @@ def test_run_writes_markdown_docs_and_d_skips_them(tmp_path): code, output = _run_bust(tmp_path, str(path), "-o", "out", "-p") assert code == 0, output markdown = (tmp_path / "out/timer/doc/timer.md").read_text() - assert "| 0 | [ctrl](#ctrl) | RW/R |" in markdown + assert re.search(r"\| +0 \| \[ctrl\]\(#ctrl\) +\| RW/R +\|", markdown) assert "### ctrl" in markdown code, output = _run_bust(tmp_path, str(path), "-o", "skipped", "-d") diff --git a/tests/test_markdown.py b/tests/test_markdown.py index 40d0793..d80e46f 100644 --- a/tests/test_markdown.py +++ b/tests/test_markdown.py @@ -1,7 +1,24 @@ """Descriptions in the Markdown documentation.""" -from bust.jinja_utils.filters import markdown_cell +from bust.jinja_utils.filters import align_markdown_tables, markdown_cell def test_markdown_cell_escapes_markup_but_keeps_code(): assert markdown_cell("a|b *c* \n`x|y` [e]") == (r"a\|b \*c\* \ `x\|y` \[e\]") + + +def test_align_markdown_tables_pads_columns_and_keeps_alignment(): + table = "| a | bb |\n|--:|---|\n| 100 | x |" + assert align_markdown_tables(table) == ( + "| a | bb |\n" "| --: | --- |\n" "| 100 | x |" + ) + + +def test_align_markdown_tables_keeps_escaped_pipes_in_their_cell(): + table = "| A | B |\n|---|---|\n| a\\|b | `x\\|y` |" + assert align_markdown_tables(table).splitlines()[2] == "| a\\|b | `x\\|y` |" + + +def test_align_markdown_tables_leaves_other_lines_alone(): + text = "# Title\n\n| not a table |\nText" + assert align_markdown_tables(text) == text diff --git a/tests/test_reserved_fields.py b/tests/test_reserved_fields.py index 199ed01..b69b0ce 100644 --- a/tests/test_reserved_fields.py +++ b/tests/test_reserved_fields.py @@ -1,5 +1,7 @@ """The documentation shows the bits that no field covers as reserved fields.""" +import re + import pytest from bust.core.bus import Bus @@ -74,8 +76,14 @@ def test_html_documentation_lists_reserved_fields(): assert ">unused" not in page +def _without_padding(markdown): + """The Markdown with the spaces that line up table columns taken out.""" + return re.sub(r" {2,}", " ", markdown) + + def test_markdown_documentation_lists_reserved_fields(): page = DocumentationGenerator(_module()).generate_markdown_documentation("1.0.0") + page = _without_padding(page) assert ( "| 31:6 | reserved | | | | Read as 0, writes have no effect. |\n" @@ -87,6 +95,7 @@ def test_markdown_documentation_lists_reserved_fields(): def test_markdown_documentation_lists_bits_below_the_lowest_field(): irq = {"name": "irq", "fields": [{"name": "done", "type": "bit", "position": 2}]} page = DocumentationGenerator(_module(irq)).generate_markdown_documentation("1.0.0") + page = _without_padding(page) assert "| 1:0 | reserved | | | | Read as 0, writes have no effect. |\n" in page From ed06b4bf98bdc1887b4261c3ca5d3a6c3d212f59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ola=20Gr=C3=B8ttvik?= Date: Fri, 30 Oct 2026 08:14:57 +0000 Subject: [PATCH 2/2] Add type hints to align_markdown_tables --- bust/jinja_utils/filters.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bust/jinja_utils/filters.py b/bust/jinja_utils/filters.py index 2980f50..490f02b 100644 --- a/bust/jinja_utils/filters.py +++ b/bust/jinja_utils/filters.py @@ -218,7 +218,7 @@ def _aligned_markdown_table(rows): return lines -def align_markdown_tables(text): +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."""