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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ 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.

### Changed
- bust builds the PDF only when `pdflatex` is on `PATH`. Without it, bust writes the `.tex` and `.html` files and prints one line saying the PDF was skipped.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ A minimal register map with one control register with two fields:
bust blinky.json -o out -p
```

This writes `out/blinky/` with the VHDL in `hdl/`, the testbench in `tb/`, the headers in `header/` and the documentation in `doc/`, as HTML and LaTeX, plus a PDF when `pdflatex` is installed. `hdl/blinky.vhd` is a starter top level that is yours to edit: bust writes it once and leaves it alone after that. Your logic reads `to_hw.ctrl.enable` and `to_hw.ctrl.rate` from `blinky_axi_endpoint`, which bust regenerates on every run.
This writes `out/blinky/` with the VHDL in `hdl/`, the testbench in `tb/`, the headers in `header/` and the documentation in `doc/`, as HTML, Markdown and LaTeX, plus a PDF when `pdflatex` is installed. `hdl/blinky.vhd` is a starter top level that is yours to edit: bust writes it once and leaves it alone after that. Your logic reads `to_hw.ctrl.enable` and `to_hw.ctrl.rate` from `blinky_axi_endpoint`, which bust regenerates on every run.

## How bust is tested

Expand Down
2 changes: 1 addition & 1 deletion bust/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
Options:
-o DIR Specify output directory (default: the directory of FILE)
-f Force overwrite of existing files, except <module>.vhd, which is yours
-d Do not generate documentation (LaTeX, HTML or PDF)
-d Do not generate documentation (LaTeX, HTML, Markdown or PDF)
-p Do not generate PDF from LaTeX, even if pdflatex is installed
-i Do not generate the include header files (.h, .hpp & .py)
--replace-top Replace <module>.vhd with a fresh starter, keeping the old file as <module>.vhd.bak
Expand Down
3 changes: 2 additions & 1 deletion bust/generation.py
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ def module_outputs(
localbus: Include the local-bus VHDL stack, the starter top level and
the testbench.
headers: Include the language headers.
documentation: Include the LaTeX and HTML documentation.
documentation: Include the LaTeX, HTML and Markdown documentation.

Returns:
The content of each file by its path relative to the output directory,
Expand Down Expand Up @@ -112,6 +112,7 @@ def module_outputs(
base = f"{name}/{settings.doc_dir}/{name}"
outputs[f"{base}.tex"] = doc.generate_tex_documentation()
outputs[f"{base}.html"] = doc.generate_html_documentation()
outputs[f"{base}.md"] = doc.generate_markdown_documentation()
return outputs


Expand Down
15 changes: 13 additions & 2 deletions bust/generators/documentation_generator.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
"""Documentation generation module for bust.

This module provides the DocumentationGenerator class for automatically generating
LaTeX and HTML documentation from module definitions. The generated documentation
LaTeX, HTML and Markdown documentation from module definitions. The generated documentation
includes register maps, bit field descriptions, and access modes.
"""

Expand Down Expand Up @@ -89,7 +89,7 @@ def _text(x, y, text, anchor, css_class):
class DocumentationGenerator:
"""Generates documentation for bus slave modules.

The DocumentationGenerator class creates LaTeX and HTML documentation with complete register
The DocumentationGenerator class creates LaTeX, HTML and Markdown documentation with complete register
specifications including addresses, bit positions, access modes, and
descriptions.

Expand Down Expand Up @@ -164,3 +164,14 @@ def generate_html_documentation(self, test_version=None):
field_notes=field_notes,
bit_diagram_svg=bit_diagram_svg,
)

def generate_markdown_documentation(self, test_version=None):
"""Generate Markdown documentation for the module, readable on GitHub.

Args:
test_version: Version string for testing (default: None, uses bust version).

Returns:
Markdown document as string.
"""
return self._render_template("markdown/documentation.j2", test_version)
4 changes: 3 additions & 1 deletion bust/jinja_utils/environment.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ def get_environment(additional_filters=None):
Environment: Configured Jinja2 environment with:
- Template directory set to bust/templates
- trim_blocks=True and lstrip_blocks=True for clean output
- Common filters registered (hex_format, utf8tolatex, utf8tohtml, indent_all)
- Common filters registered (hex_format, utf8tolatex, utf8tohtml, markdown_cell, indent_all)
- Additional filters if provided
"""
# Get template directory relative to this module
Expand All @@ -50,13 +50,15 @@ def get_environment(additional_filters=None):
# Register common filters used across modules
from bust.jinja_utils.filters import (
align,
markdown_cell,
to_binary,
utf8tohtml,
utf8tolatex,
wrap,
)

env.filters["align"] = align
env.filters["markdown_cell"] = markdown_cell
env.filters["to_binary"] = to_binary
env.filters["utf8tolatex"] = utf8tolatex
env.filters["utf8tohtml"] = utf8tohtml
Expand Down
19 changes: 19 additions & 0 deletions bust/jinja_utils/filters.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
- wrap: Break a call that is too long after a comma.
- 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.

Copyright (c) 2025 Ola Groettvik
Licensed under the Apache License, Version 2.0. See the LICENSE file for details.
Expand Down Expand Up @@ -156,3 +157,21 @@ def _convert_code_spans(text, convert, mark_code):
convert(part) if i % 2 == 0 else mark_code(convert(part))
for i, part in enumerate(parts)
)


_MARKDOWN_SPECIAL = re.compile(r"([\\*\[\]<>|])")


def markdown_cell(text):
"""Escape text for one line of Markdown, such as a table cell.

A `code` span is kept, but a | in it is still escaped, since GitHub splits
the cells of a table row before it reads code spans. Line breaks become
spaces.
"""
parts = re.split(r"(`[^`]*`)", str(text))
escaped = "".join(
part.replace("|", "\\|") if i % 2 else _MARKDOWN_SPECIAL.sub(r"\\\1", part)
for i, part in enumerate(parts)
)
return " ".join(escaped.split())
56 changes: 56 additions & 0 deletions bust/templates/markdown/documentation.j2
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
{% macro bits(high, low) %}{{ high }}{% if high > low %}:{{ low }}{% endif %}{% endmacro %}
{% macro field_notes(field) %}
{% set notes = [] %}
{% if field.description %}{% set _ = notes.append(field.description | markdown_cell) %}{% endif %}
{% if field.onread %}{% set _ = notes.append("onread: " ~ field.onread.value ~ ".") %}{% endif %}
{% if field.onwrite %}{% set _ = notes.append("onwrite: " ~ field.onwrite.value ~ ".") %}{% endif %}
{% if field.singlepulse %}{% set _ = notes.append("singlepulse.") %}{% endif %}
{% set modifiers = [] %}
{% for name in ["we", "wel", "hwset", "hwclr", "swmod", "swacc"] if field[name] %}{% set _ = modifiers.append(name) %}{% endfor %}
{% if modifiers %}{% set _ = notes.append("Modifiers: " ~ modifiers | join(", ") ~ ".") %}{% endif %}
{% if field.is_enum %}
{% set values = [] %}
{% for e in field.enums %}{% set _ = values.append(e.name ~ "=" ~ e.value) %}{% endfor %}
{% set _ = notes.append("Values: " ~ values | join(", ") ~ ".") %}
{% endif %}
{{ notes | join(" ") }}
{%- endmacro %}
# {{ module.name }}

Generated by bust v{{ version }}. {% if module.version %}Version: {{ module.version | markdown_cell }}. {% endif %}Register map hash: `0x{{ module.regmap_hash_hex }}`.
{% if module.description %}

{{ module.description | markdown_cell }}
{% endif %}

## Register list

| # | Name | SW/HW | Address | Type | Width | Reset |
|--:|------|-------|---------|------|------:|-------|
{% for reg in module.registers %}
| {{ loop.index0 }} | [{{ reg.name }}](#{{ reg.name | lower }}) | {{ reg.sw.value.upper() }}/{{ reg.hw.value.upper() }} | `0x{{ "%08X" | format(reg.address) }}` | {{ reg.type.value.upper() }} | {{ reg.width }} | `0x{{ "%X" | format(reg.reset[2:]|int(base=16)) }}` |
{% endfor %}

## Registers
{% for reg in module.registers %}

### {{ reg.name }}

Address `0x{{ "%08X" | format(reg.address) }}`, {{ reg.sw.value.upper() }}/{{ reg.hw.value.upper() }}, reset `0x{{ "%X" | format(reg.reset[2:]|int(base=16)) }}`.
{% if reg.description %}

{{ reg.description | markdown_cell }}
{% endif %}

| Bits | Name | SW | HW | Reset | Description |
|------|------|----|----|-------|-------------|
{% set free = namespace(high=module.data_width - 1) %}
{% for field in reg.effective_fields | reverse %}
{% if field.pos_high < free.high %}
| {{ bits(free.high, field.pos_high + 1) }} | unused | | | | |
{% endif %}
{% set notes = field_notes(field) %}
| {{ bits(field.pos_high, field.pos_low) }} | {{ field.name }} | {{ field.sw.value }} | {{ field.hw.value }} | `0x{{ "%X" | format(field.reset[2:]|int(base=16)) }}` |{% if notes %} {{ notes }}{% endif %} |
{% set free.high = field.pos_low - 1 %}
{% endfor %}
{% endfor %}
2 changes: 1 addition & 1 deletion docs/addressing.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,5 +139,5 @@ your software adds the base address.

In the headers, `_OFFSET` also names the lowest bit of a field, as in
`<MODULE>_<REG>_<FIELD>_OFFSET`. That is a bit position inside the register,
not an address. [Headers and documentation](headers-and-docs.md#constant-names)
not an address. [Software headers](headers.md#constant-names)
lists the constants.
2 changes: 1 addition & 1 deletion docs/buses.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ compile `components/ipbus_core/firmware/hdl/ipbus_package.vhd` from the
- With an `addr_width` below 32, the endpoint ignores the upper bits of
`ipb_addr`, so decode them before the module, as an IPBus fabric does.
- bust also writes an IPBus address table for uHAL. See
[Headers and documentation](headers-and-docs.md).
[Software headers](headers.md#ipbus-address-table).

## SBI

Expand Down
16 changes: 8 additions & 8 deletions docs/command-line.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,8 @@ and exit with status 1.
|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-o DIR` | Write the output under `DIR` instead of next to the JSON file. See [Output directory](#output-directory). |
| `-f` | Overwrite existing files without asking, except `<module>.vhd`, which is yours. See [Existing files](#existing-files). |
| `-d` | Do not write the documentation: no `.tex` or `.html` file and no PDF. |
| `-p` | Write the `.tex` and `.html` files, but do not run `pdflatex` to make the PDF, even when it is installed. |
| `-d` | Do not write the documentation: no `.tex`, `.html` or `.md` file and no PDF. |
| `-p` | Write the `.tex`, `.html` and `.md` files, but do not run `pdflatex` to make the PDF, even when it is installed. |
| `-i` | Do not write the headers: the `.h`, `.hpp` and `.py` files, and for IPBus the `.xml` address table. |
| `--replace-top` | Replace `<module>.vhd` with a fresh starter and keep the old file as `<module>.vhd.bak`. Asks first unless you add `-f`. See [Your top level](#your-top-level). |
| `-a` | Give every register a new address and save the JSON file. Generates nothing. With `-f`, saves without asking. See [Renumber addresses](#renumber-addresses). |
Expand All @@ -50,8 +50,7 @@ and exit with status 1.
| `-h`, `--help` | Print the usage and a short description of each option, then exit. |

Every run that generates files writes the VHDL files and the testbench. No
option turns them off. [Headers and documentation](headers-and-docs.md)
describes the headers, the address table and the documentation.
option turns them off. [Software headers](headers.md) describes the headers and the address table, and [Documentation](documentation.md) the documentation.

## Output directory

Expand All @@ -70,6 +69,7 @@ out/
│ ├── example_ipbus.aux
│ ├── example_ipbus.html
│ ├── example_ipbus.log
│ ├── example_ipbus.md
│ ├── example_ipbus.pdf
│ └── example_ipbus.tex
├── hdl/
Expand All @@ -91,8 +91,8 @@ out/
|-----------|-----------------------------------------------------------------------------------------------------------|----------------------------------------------------|
| `hdl/` | `<module>_localbus_pkg.vhd`, `<module>_regfile_pkg.vhd`, `<module>_regfile.vhd`, the endpoint, `<module>.vhd` | [Generated HDL](generated-hdl.md) |
| `tb/` | `<module>_tb.vhd` | [Testbenches](testbenches.md) |
| `header/` | `<module>.h`, `<module>.hpp`, `<module>.py`, and `<module>.xml` for IPBus | [Headers and documentation](headers-and-docs.md) |
| `doc/` | `<module>.tex`, `<module>.html`, and with `pdflatex` installed `<module>.pdf` and its `.aux` and `.log` files | [Headers and documentation](headers-and-docs.md) |
| `header/` | `<module>.h`, `<module>.hpp`, `<module>.py`, and `<module>.xml` for IPBus | [Software headers](headers.md) |
| `doc/` | `<module>.tex`, `<module>.html`, `<module>.md`, and with `pdflatex` installed `<module>.pdf` and its `.aux` and `.log` files | [Documentation](documentation.md) |

The endpoint file is named after the bus:

Expand Down Expand Up @@ -291,7 +291,7 @@ Delete removes one.
### The overview

`o` shows the whole register map the way the
[documentation](headers-and-docs.md) does. It has the module's name, version,
[documentation](documentation.md) does. It has the module's name, version,
register map hash and bus, then the register list with the number, name,
software and hardware access, address, type, width and reset of each register.
Then each register follows with its address, its description and a bit
Expand Down Expand Up @@ -390,7 +390,7 @@ pdflatex is not on PATH, so bust skipped the PDF. The documentation is in /path/
When `pdflatex` runs but reports errors, bust prints
`pdflatex reported errors. See <doc dir>/<module>.log`. In both cases bust
still exits with status 0, since every other file was written.
[Headers and documentation](headers-and-docs.md) describes the PDF step.
[Documentation](documentation.md#pdf) describes the PDF step.

An error in the register map is printed as a message that names the problem,
and bust exits with status 1. A value of the wrong form gives the file, the
Expand Down
3 changes: 2 additions & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@
version = release

extensions = ["myst_parser"]
myst_heading_anchors = 3
# 5 so the register links in the included example Markdown resolve.
myst_heading_anchors = 5
exclude_patterns = ["_build"]

html_theme = "furo"
Expand Down
Loading
Loading