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
6 changes: 6 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ build:
os: ubuntu-24.04
tools:
python: "3.13"
# pdflatex and the LaTeX packages of the documentation, for the example PDF
# that docs/conf.py builds.
apt_packages:
- texlive-latex-base
- texlive-latex-recommended
- texlive-latex-extra

sphinx:
configuration: docs/conf.py
Expand Down
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@ 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.

### 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.
- `<module>_regfile_pkg` merges `base_match` and `above_registers` into one function, `is_in_range`.

### Removed
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 LaTeX documentation in `doc/`. `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 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
4 changes: 2 additions & 2 deletions bust/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
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 (neither LaTeX nor PDF)
-p Do not generate PDF from LaTeX
-d Do not generate documentation (LaTeX, HTML 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
-a Update register addresses and save JSON file (with -f, without asking)
Expand Down
9 changes: 5 additions & 4 deletions bust/editor/diagram.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ class _Segment:
high: int
low: int
reset: str
is_unused: bool = False

@property
def width(self) -> int:
Expand All @@ -32,7 +33,7 @@ def _reset(text: str, width: int) -> str:
return str(value) if width < 2 else f"0x{value:X}"


def _segments(register: Register, data_width: int) -> List[_Segment]:
def bit_segments(register: Register, data_width: int) -> List[_Segment]:
"""The fields of `register` from the highest bit down, with the unused
bits between them."""
if register.type == RegisterType.FIELDS:
Expand All @@ -47,11 +48,11 @@ def _segments(register: Register, data_width: int) -> List[_Segment]:
next_high = data_width - 1
for segment in sorted(used, key=lambda s: s.high, reverse=True):
if segment.high < next_high:
segments.append(_Segment("unused", next_high, segment.high + 1, "-"))
segments.append(_Segment("unused", next_high, segment.high + 1, "-", True))
segments.append(segment)
next_high = segment.low - 1
if next_high >= 0:
segments.append(_Segment("unused", next_high, 0, "-"))
segments.append(_Segment("unused", next_high, 0, "-", True))
return segments


Expand All @@ -69,7 +70,7 @@ def bit_diagram(register: Register, data_width: int) -> List[str]:
the field names, and the reset values."""
bit = bit_width(data_width)
numbers = top = names = bottom = resets = ""
for number, segment in enumerate(_segments(register, data_width)):
for number, segment in enumerate(bit_segments(register, data_width)):
high, low = str(segment.high), str(segment.low)
bits = high if segment.width == 1 else f"{high} {low}"
# A box grows past its bits rather than cut a name short.
Expand Down
59 changes: 36 additions & 23 deletions 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 documentation.
documentation: Include the LaTeX and HTML documentation.

Returns:
The content of each file by its path relative to the output directory,
Expand Down Expand Up @@ -108,9 +108,10 @@ def module_outputs(
if module.bus.bus_type == "ipbus":
outputs[f"{base}.xml"] = header.generate_ipbus_addr_table()
if documentation:
outputs[f"{name}/{settings.doc_dir}/{name}.tex"] = DocumentationGenerator(
module
).generate_tex_documentation()
doc = DocumentationGenerator(module)
base = f"{name}/{settings.doc_dir}/{name}"
outputs[f"{base}.tex"] = doc.generate_tex_documentation()
outputs[f"{base}.html"] = doc.generate_html_documentation()
return outputs


Expand Down Expand Up @@ -199,7 +200,7 @@ def generate_output(settings, module, gen_settings):
- gen_localbus: Generate the local-bus VHDL stack and testbench
- gen_header: Generate language headers
- gen_doc: Generate documentation
- gen_pdf: Generate PDF from LaTeX
- gen_pdf: Generate PDF from LaTeX, if pdflatex is installed
"""
proj_dir = os.path.expanduser(gen_settings["dir"])
logger.info(f"Project path: {os.path.abspath(proj_dir)}")
Expand All @@ -220,22 +221,34 @@ def generate_output(settings, module, gen_settings):
else:
write_string_to_file(content, filename, directory, gen_settings["force_ow"])

mod_doc = os.path.join(proj_dir, module.name, settings.doc_dir)
if gen_settings["gen_pdf"]:
logger.info("Generating Documentation PDF...")
try:
status = subprocess.call(
[
"pdflatex",
"--interaction=batchmode",
f"--output-directory={mod_doc}",
os.path.join(mod_doc, module.name + ".tex"),
],
stdout=subprocess.DEVNULL,
)
except OSError as e:
logger.error(f"Could not run pdflatex ({e}). Use -p to skip the PDF.")
else:
if status != 0:
log = os.path.join(mod_doc, module.name + ".log")
logger.warning(f"pdflatex reported errors. See {log}")
_build_pdf(module, os.path.join(proj_dir, module.name, settings.doc_dir))


def _build_pdf(module, mod_doc):
"""Run pdflatex on <module>.tex, or say that the PDF was skipped when
pdflatex is not installed. Neither stops the run."""
pdflatex = shutil.which("pdflatex")
if pdflatex is None:
logger.info(
"pdflatex is not on PATH, so bust skipped the PDF. "
f"The documentation is in {os.path.join(mod_doc, module.name + '.html')}."
)
return
logger.info("Generating Documentation PDF...")
try:
status = subprocess.call(
[
pdflatex,
"--interaction=batchmode",
f"--output-directory={mod_doc}",
os.path.join(mod_doc, module.name + ".tex"),
],
stdout=subprocess.DEVNULL,
)
except OSError as e:
logger.error(f"Could not run pdflatex ({e}). Use -p to skip the PDF.")
else:
if status != 0:
log = os.path.join(mod_doc, module.name + ".log")
logger.warning(f"pdflatex reported errors. See {log}")
106 changes: 103 additions & 3 deletions bust/generators/documentation_generator.py
Original file line number Diff line number Diff line change
@@ -1,19 +1,95 @@
"""Documentation generation module for bust.

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

from html import escape

from bust._version import __VERSION__
from bust.core.enums import RegisterType
from bust.editor.diagram import (
bit_segments,
field_notes,
register_heading,
register_list,
)
from bust.jinja_utils.environment import render_template

# 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.
_CHAR_WIDTH = 7
_NUMBERS_HEIGHT = 16
_RESET_HEIGHT = 18
_MIN_BOX_HEIGHT = 28


def bit_diagram_svg(register, data_width):
"""An inline SVG of the bits of `register`, laid out as the LaTeX register
package draws them: a box per field with its name, the numbers of its
highest and lowest bit above it, and its reset value below.

A name too long for its box is turned on its side, and the boxes grow
taller to fit the longest such name.
"""
bit = 24 if data_width <= 32 else 14
segments = bit_segments(register, data_width)
is_turned = [len(s.name) * _CHAR_WIDTH + 6 > s.width * bit for s in segments]
box_height = max(
[_MIN_BOX_HEIGHT]
+ [
len(s.name) * _CHAR_WIDTH + 10
for s, turned in zip(segments, is_turned)
if turned
]
)
width = data_width * bit
box_top = _NUMBERS_HEIGHT
height = box_top + box_height + _RESET_HEIGHT
parts = [
f'<svg class="bits" xmlns="http://www.w3.org/2000/svg" '
f'viewBox="0 0 {width + 2} {height}" width="{width + 2}" '
f'role="img" aria-label="Bits of {escape(register.name)}">'
]
x = 1
for segment, turned in zip(segments, is_turned):
w = segment.width * bit
middle = x + w / 2
name_y = box_top + box_height / 2
if segment.width == 1:
parts.append(_text(middle, box_top - 4, segment.high, "middle", "num"))
else:
parts.append(_text(x + 3, box_top - 4, segment.high, "start", "num"))
parts.append(_text(x + w - 3, box_top - 4, segment.low, "end", "num"))
css_class = "unused" if segment.is_unused else "field"
parts.append(
f'<rect class="{css_class}" x="{x}" y="{box_top}" '
f'width="{w}" height="{box_height}"/>'
)
rotate = f' transform="rotate(-90 {middle} {name_y})"' if turned else ""
parts.append(
f'<text class="name" x="{middle}" y="{name_y}"{rotate} '
f'text-anchor="middle" dominant-baseline="central">'
f"{escape(segment.name)}</text>"
)
parts.append(_text(middle, height - 4, segment.reset, "middle", "reset"))
x += w
parts.append("</svg>")
return "".join(parts)


def _text(x, y, text, anchor, css_class):
return (
f'<text class="{css_class}" x="{x}" y="{y}" '
f'text-anchor="{anchor}">{escape(str(text))}</text>'
)


class DocumentationGenerator:
"""Generates documentation for bus slave modules.

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

Expand All @@ -29,7 +105,7 @@ def __init__(self, module):
"""
self.module = module

def _render_template(self, template_name, version=None):
def _render_template(self, template_name, version=None, **context):
"""Render a Jinja2 template with module context.

Args:
Expand All @@ -48,6 +124,7 @@ def _render_template(self, template_name, version=None):
"module": self.module,
"version": version,
"reg_type_fields": RegisterType.FIELDS,
**context,
},
)

Expand All @@ -64,3 +141,26 @@ def generate_tex_documentation(self, test_version=None):
LaTeX document source code as string.
"""
return self._render_template("latex/documentation.j2", test_version)

def generate_html_documentation(self, test_version=None):
"""Generate the documentation as one self-contained HTML page.

It follows the layout of the LaTeX documentation, with links from the
register list and a sidebar to each register, and a print stylesheet.

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

Returns:
HTML document as string.
"""
headers, rows = register_list(self.module)
return self._render_template(
"html/documentation.j2",
test_version,
list_headers=headers,
list_rows=zip(rows, self.module.registers),
register_heading=register_heading,
field_notes=field_notes,
bit_diagram_svg=bit_diagram_svg,
)
27 changes: 19 additions & 8 deletions bust/jinja_utils/environment.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,17 @@
from bust._version import __VERSION__


def generated_by() -> str:
"""The first line of every generated file: the bust version and the time.

SOURCE_DATE_EPOCH, if set, gives the time, for reproducible output.
"""
def generated_at() -> str:
"""The time of the run. SOURCE_DATE_EPOCH, if set, gives the time, for
reproducible output."""
epoch = os.environ.get("SOURCE_DATE_EPOCH")
when = datetime.fromtimestamp(int(epoch), timezone.utc) if epoch else datetime.now()
return f"Generated by bust v{__VERSION__} {when:%Y-%m-%d %H:%M}"
return f"{when:%Y-%m-%d %H:%M}"


def generated_by() -> str:
"""The first line of every generated file: the bust version and the time."""
return f"Generated by bust v{__VERSION__} {generated_at()}"


def get_environment(additional_filters=None):
Expand All @@ -31,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, indent_all)
- Common filters registered (hex_format, utf8tolatex, utf8tohtml, indent_all)
- Additional filters if provided
"""
# Get template directory relative to this module
Expand All @@ -45,14 +48,22 @@ def get_environment(additional_filters=None):
)

# Register common filters used across modules
from bust.jinja_utils.filters import align, to_binary, utf8tolatex, wrap
from bust.jinja_utils.filters import (
align,
to_binary,
utf8tohtml,
utf8tolatex,
wrap,
)

env.filters["align"] = align
env.filters["to_binary"] = to_binary
env.filters["utf8tolatex"] = utf8tolatex
env.filters["utf8tohtml"] = utf8tohtml
env.filters["wrap"] = wrap

env.globals["generated_by"] = generated_by
env.globals["generated_at"] = generated_at

# Register any additional filters provided
if additional_filters:
Expand Down
Loading
Loading