diff --git a/.readthedocs.yaml b/.readthedocs.yaml index fd497d03..ad45a5b1 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ecf2308..f7c211dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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/.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. - `_regfile_pkg` merges `base_match` and `above_registers` into one function, `is_in_range`. ### Removed diff --git a/README.md b/README.md index c6d74526..509eee1e 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/bust/__main__.py b/bust/__main__.py index 369ae04d..27566f18 100644 --- a/bust/__main__.py +++ b/bust/__main__.py @@ -9,8 +9,8 @@ Options: -o DIR Specify output directory (default: the directory of FILE) -f Force overwrite of existing files, except .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 .vhd with a fresh starter, keeping the old file as .vhd.bak -a Update register addresses and save JSON file (with -f, without asking) diff --git a/bust/editor/diagram.py b/bust/editor/diagram.py index 26a7de37..41b6dabf 100644 --- a/bust/editor/diagram.py +++ b/bust/editor/diagram.py @@ -21,6 +21,7 @@ class _Segment: high: int low: int reset: str + is_unused: bool = False @property def width(self) -> int: @@ -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: @@ -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 @@ -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. diff --git a/bust/generation.py b/bust/generation.py index 1fbb6d5f..21369eec 100644 --- a/bust/generation.py +++ b/bust/generation.py @@ -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, @@ -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 @@ -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)}") @@ -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 .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}") diff --git a/bust/generators/documentation_generator.py b/bust/generators/documentation_generator.py index dc81db9f..024b3229 100644 --- a/bust/generators/documentation_generator.py +++ b/bust/generators/documentation_generator.py @@ -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'' + ] + 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'' + ) + rotate = f' transform="rotate(-90 {middle} {name_y})"' if turned else "" + parts.append( + f'' + f"{escape(segment.name)}" + ) + parts.append(_text(middle, height - 4, segment.reset, "middle", "reset")) + x += w + parts.append("") + return "".join(parts) + + +def _text(x, y, text, anchor, css_class): + return ( + f'{escape(str(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. @@ -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: @@ -48,6 +124,7 @@ def _render_template(self, template_name, version=None): "module": self.module, "version": version, "reg_type_fields": RegisterType.FIELDS, + **context, }, ) @@ -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, + ) diff --git a/bust/jinja_utils/environment.py b/bust/jinja_utils/environment.py index 534515b1..4a03d982 100644 --- a/bust/jinja_utils/environment.py +++ b/bust/jinja_utils/environment.py @@ -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): @@ -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 @@ -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: diff --git a/bust/jinja_utils/filters.py b/bust/jinja_utils/filters.py index 43920c7d..d35a9166 100644 --- a/bust/jinja_utils/filters.py +++ b/bust/jinja_utils/filters.py @@ -8,11 +8,13 @@ - align: Line up a token, such as ":" or "<=", in a column. - 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 . Copyright (c) 2025 Ola Groettvik Licensed under the Apache License, Version 2.0. See the LICENSE file for details. """ +import html import re @@ -136,12 +138,21 @@ def utf8tolatex(text): unknown_char_policy="ignore", unknown_char_warning=False, ) + return _convert_code_spans( + text, encoder.unicode_to_latex, lambda code: "\\texttt{" + code + "}" + ) + + +def utf8tohtml(text): + """Escape text for HTML, with a `code` span as , as utf8tolatex sets + it in typewriter type.""" + return _convert_code_spans(text, html.escape, lambda code: f"{code}") + + +def _convert_code_spans(text, convert, mark_code): + """Convert all of `text`, and mark each `code` span in it after converting.""" parts = re.split(r"`([^`]*)`", str(text)) return "".join( - ( - encoder.unicode_to_latex(part) - if i % 2 == 0 - else "\\texttt{" + encoder.unicode_to_latex(part) + "}" - ) + convert(part) if i % 2 == 0 else mark_code(convert(part)) for i, part in enumerate(parts) ) diff --git a/bust/templates/html/documentation.j2 b/bust/templates/html/documentation.j2 new file mode 100644 index 00000000..6ca4879b --- /dev/null +++ b/bust/templates/html/documentation.j2 @@ -0,0 +1,116 @@ + + + + + + +{{ module.name | e }} + + + + +
+
Generated by bust v{{ version }}{% if module.version %}Version: {{ module.version | e }}{% endif %}
+
+

{{ module.name | e }}

+{% if module.version %} +

Version: {{ module.version | e }}

+{% endif %} +

Register map hash: 0x{{ module.regmap_hash_hex }}

+

{{ generated_at() }}

+
+{% if module.description %} +

{{ module.description | utf8tohtml }}

+{% endif %} + +

1 Register List

+
+ + +{% for header in list_headers %}{% endfor %} + + +{% for row, reg in list_rows %} + +{% endfor %} + +
{{ header | e }}
{{ row[0] }}{{ row[1] | e }}{{ row[2] }}{{ row[3] }}{{ row[4] }}{{ row[5] }}{{ row[6] }}
+
+ +

2 Registers

+{% for reg in module.registers %} +{% set title, address = register_heading(reg) %} +
+

{{ title | e }}{{ address }}

+{% if reg.description %} +

{{ reg.description | utf8tohtml }}

+{% endif %} +
{{ bit_diagram_svg(reg, module.data_width) }}
+{% if reg.type == reg_type_fields %} +
+{% for name, note in field_notes(reg) %} +
{{ name | e }}
{{ note | utf8tohtml }}
+{% endfor %} +
+{% endif %} +

Back to the register list

+
+{% endfor %} +
+ + diff --git a/docs/_static/custom.css b/docs/_static/custom.css index f3009dd2..f4576e9b 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -72,3 +72,14 @@ section#bust > h1 { .addr-fig .row { font-weight: 700; } + +/* The example HTML documentation on the Headers and documentation page. The + page keeps its own white background in both modes, as it would on its own. */ +.doc-example { + display: block; + width: 100%; + height: 36rem; + margin: 1.5rem 0; + border: 1px solid var(--color-background-border); + background: #fff; +} diff --git a/docs/command-line.md b/docs/command-line.md index 7747e730..72bd6a5e 100644 --- a/docs/command-line.md +++ b/docs/command-line.md @@ -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 `.vhd`, which is yours. See [Existing files](#existing-files). | -| `-d` | Do not write the documentation, neither the `.tex` file nor the PDF. | -| `-p` | Write the `.tex` file, but do not run `pdflatex` to make the PDF. | +| `-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. | | `-i` | Do not write the headers: the `.h`, `.hpp` and `.py` files, and for IPBus the `.xml` address table. | | `--replace-top` | Replace `.vhd` with a fresh starter and keep the old file as `.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). | @@ -68,6 +68,7 @@ out/ └── example_ipbus/ ├── doc/ │ ├── example_ipbus.aux + │ ├── example_ipbus.html │ ├── example_ipbus.log │ ├── example_ipbus.pdf │ └── example_ipbus.tex @@ -91,7 +92,7 @@ out/ | `hdl/` | `_localbus_pkg.vhd`, `_regfile_pkg.vhd`, `_regfile.vhd`, the endpoint, `.vhd` | [Generated HDL](generated-hdl.md) | | `tb/` | `_tb.vhd` | [Testbenches](testbenches.md) | | `header/` | `.h`, `.hpp`, `.py`, and `.xml` for IPBus | [Headers and documentation](headers-and-docs.md) | -| `doc/` | `.tex`, `.pdf`, and the `.aux` and `.log` files from `pdflatex` | [Headers and documentation](headers-and-docs.md) | +| `doc/` | `.tex`, `.html`, and with `pdflatex` installed `.pdf` and its `.aux` and `.log` files | [Headers and documentation](headers-and-docs.md) | The endpoint file is named after the bus: @@ -380,10 +381,10 @@ Generating Module Documentation... Generating Documentation PDF... ``` -When `pdflatex` is not on your `PATH`, the last line is followed by: +When `pdflatex` is not on your `PATH`, the last line is instead: ```text -Could not run pdflatex ([Errno 2] No such file or directory: 'pdflatex'). Use -p to skip the PDF. +pdflatex is not on PATH, so bust skipped the PDF. The documentation is in /path/to/out/example_axi/doc/example_axi.html. ``` When `pdflatex` runs but reports errors, bust prints diff --git a/docs/conf.py b/docs/conf.py index 46d6b0a2..2c740c51 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,4 +1,9 @@ # SPDX-License-Identifier: Apache-2.0 +import os +import shutil +import subprocess +import tempfile + from bust._version import __VERSION__ project = "bust" @@ -55,3 +60,53 @@ "color-highlighted-background": "#2f2c2a", }, } + + +# The documentation bust generated for the prototype example, put into the +# built site so the docs can show it. Both come from the committed goldens, +# which the tests keep in step with the generator: the HTML is copied, and the +# PDF is built from the .tex. Read the Docs installs pdflatex for that (see +# .readthedocs.yaml). Elsewhere the PDF is left out when pdflatex is missing. +_EXAMPLE_DOC = os.path.join("..", "example", "example_prototype", "doc", "prototype") + + +def _add_example_docs(app, exception): + if exception is not None or app.builder.format != "html": + return + examples_dir = os.path.join(app.outdir, "examples") + os.makedirs(examples_dir, exist_ok=True) + example = os.path.join(app.confdir, _EXAMPLE_DOC) + shutil.copy(example + ".html", examples_dir) + _build_example_pdf(example + ".tex", examples_dir) + + +def _build_example_pdf(tex, out_dir): + pdflatex = shutil.which("pdflatex") + if pdflatex is None: + if os.environ.get("READTHEDOCS") == "True": + raise RuntimeError( + "pdflatex is missing, so the example PDF cannot be built" + ) + return + with tempfile.TemporaryDirectory() as build_dir: + # The second run resolves the references the first one writes to the + # .aux file. + for _ in range(2): + subprocess.run( + [ + pdflatex, + "--interaction=batchmode", + f"--output-directory={build_dir}", + tex, + ], + stdout=subprocess.DEVNULL, + check=True, + # The same date as the HTML example, which pins it for the goldens. + env=dict(os.environ, SOURCE_DATE_EPOCH="0", FORCE_SOURCE_DATE="1"), + ) + name = os.path.splitext(os.path.basename(tex))[0] + ".pdf" + shutil.copy(os.path.join(build_dir, name), out_dir) + + +def setup(app): + app.connect("build-finished", _add_example_docs) diff --git a/docs/getting-started.md b/docs/getting-started.md index 76e4f037..5f75ba88 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -86,6 +86,7 @@ bust writes one directory per module: ```text out/timer/ ├── doc/ +│ ├── timer.html │ ├── timer.pdf │ └── timer.tex ├── hdl/ @@ -102,7 +103,7 @@ out/timer/ └── timer_tb.vhd ``` -The PDF needs `pdflatex` on your `PATH`. Add `-p` to skip it. +`timer.html` is the documentation of the register map. Open it in a browser. bust writes `timer.pdf` only when `pdflatex` is on your `PATH`, and `-p` skips it. [Command line](command-line.md) describes every option. ## Use the VHDL diff --git a/docs/headers-and-docs.md b/docs/headers-and-docs.md index f7e93ccf..74cc3bf3 100644 --- a/docs/headers-and-docs.md +++ b/docs/headers-and-docs.md @@ -1,9 +1,7 @@ # Headers and documentation Next to the VHDL, bust writes headers that give software the addresses and bit -positions of the registers, an address table for IPBus, and a LaTeX document -of the register map. This page describes what each file holds and how to use -it. +positions of the registers, an address table for IPBus, and documentation of the register map as LaTeX, HTML and, when `pdflatex` is installed, PDF. This page describes what each file holds and how to use it. ## Files @@ -18,7 +16,8 @@ output directory of the module described in | `.py` | Python module with constants in a class | Unless you give `-i` | | `.xml` | IPBus address table for uHAL | For the `ipbus` bus type, unless you give `-i` | | `.tex` | LaTeX source of the documentation | Unless you give `-d` | -| `.pdf` | The documentation as PDF | Unless you give `-d` or `-p`. Needs `pdflatex`. | +| `.html`| The documentation as one HTML page | Unless you give `-d` | +| `.pdf` | The documentation as PDF | Unless you give `-d` or `-p`, when `pdflatex` is on your `PATH` | ## Constant names @@ -264,11 +263,11 @@ module: ## Documentation -`doc/.tex` is a LaTeX document of the register map. It contains: +bust writes the documentation of the register map twice, as `doc/.tex` and as `doc/.html`, with the same content and layout. Neither needs anything beyond bust itself. Both contain: - A title with the module name, the `version` of the module, the hash of the register map, and the date and - time the PDF was built. Each page has `Generated by bust` and the bust + time of the run (for the PDF, the time it was built). Each page has `Generated by bust` and the bust version at the top. - The `description` of the module. - **Register List**, a table of every register with its number, name, software @@ -280,8 +279,7 @@ module: and its `onread`, `onwrite`, `singlepulse` and enumeration values where it has them. -In descriptions, a `` `code` `` span is set in typewriter type, and a character -that LaTeX cannot print, such as an emoji, is left out. +In descriptions, a `` `code` `` span is set in typewriter type. In the LaTeX document, a character that LaTeX cannot print, such as an emoji, is left out. This is the section for `reg11` from `prototype.tex`: @@ -297,9 +295,17 @@ This is the section for `reg11` from `prototype.tex`: \end{register} ``` +### The HTML page + +`doc/.html` is one self-contained file: the styles are in the page and the bit diagrams are inline SVG, so it opens in any browser and can be copied or served on its own. On top of the layout of the LaTeX document it adds links: each row of the register list links to the section of its register, a sidebar lists every register, and each section links back to the register list. The page has a print stylesheet that hides the sidebar and the links back, so printing it to PDF from a browser gives a clean document without `pdflatex`. + +This is the page bust writes for the prototype example, `example/example_prototype.json` in the repository. Open it on its own to try the links and the print layout. + + + ### The PDF -After writing the `.tex` file, bust runs `pdflatex` once to make the PDF: +When `pdflatex` is on your `PATH`, bust runs it once on the `.tex` file to make the PDF: ```bash pdflatex --interaction=batchmode --output-directory= /.tex @@ -312,6 +318,12 @@ and `listings`. On Debian and Ubuntu, the packages `texlive-latex-base`, `pdflatex` writes `.pdf` to `doc/`, together with its `.aux` and `.log` files. +This is the PDF of the prototype example. Open it on its own if your browser does not show it here. + + + +When `pdflatex` is not on your `PATH`, bust writes the `.tex` and `.html` files, prints `pdflatex is not on PATH, so bust skipped the PDF.` followed by the path of the HTML page, and exits with status 0. + bust runs `pdflatex` in batch mode and does not show its output. When `pdflatex` reports errors, bust prints `pdflatex reported errors. See /.log`. When it cannot run `pdflatex` at all, it prints @@ -319,5 +331,5 @@ bust runs `pdflatex` in batch mode and does not show its output. When carries on: the other files are written and bust exits with status 0. To build the PDF in your own flow instead, give `-p`. bust then writes the -`.tex` file but does not run `pdflatex`. Give `-d` to skip the documentation +`.tex` and `.html` files but does not run `pdflatex`. Give `-d` to skip the documentation altogether. diff --git a/docs/index.md b/docs/index.md index bfd74e11..e231a480 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,7 @@ **bust** generates the register file of an FPGA or ASIC module from a JSON register map. From one file it writes the VHDL register file with its bus endpoint, a self-checking UVVM testbench, C, C++ and Python headers, an IPBus -address table and LaTeX documentation. +address table and documentation as HTML, LaTeX and PDF. bust supports six buses: AXI4-Lite, IPBus, SBI, Avalon-MM, Wishbone and APB. @@ -53,7 +53,7 @@ testbench of every bus in CI. - [Generated HDL](generated-hdl.md): the generated files, the records and how to instantiate the module. - [Headers and documentation](headers-and-docs.md): the C, C++ and Python - headers, the IPBus address table and the LaTeX documentation. + headers, the IPBus address table and the documentation. - [Testbenches](testbenches.md): what the testbench checks and how to run it. - [Command line](command-line.md): every option of the `bust` command. diff --git a/docs/register-map-format.md b/docs/register-map-format.md index 676b4813..68ecb39c 100644 --- a/docs/register-map-format.md +++ b/docs/register-map-format.md @@ -174,7 +174,7 @@ the timing of each protocol. | `name` | string | required | Module name. It names the generated files and VHDL units, such as `uart_regfile` and `uart_regfile_pkg`. See [Names](#names). | | `register` | list | required | The registers, see [Registers](#registers). | | `version` | string | `""` | The version of the register map. Every generated file carries it, see [Version and hash](#version-and-hash). Printable ASCII characters other than `"`, `\`, `;` and `=`. A module with a `version` register needs the form `MAJOR.MINOR` or `MAJOR.MINOR.PATCH`. | -| `description` | string | `""` | Shown in the LaTeX documentation. | +| `description` | string | `""` | Shown in the documentation. | | `byte_addressable` | boolean | from the bus | `true` if an address counts bytes, `false` if it counts data words. See [Byte and word addresses](#byte-and-word-addresses). | ### Version and hash @@ -201,7 +201,7 @@ Both appear in every output: | C header | `_REGMAP_VERSION` | `_REGMAP_HASH` | | C++ and Python headers | `REGMAP_VERSION` | `REGMAP_HASH` | | IPBus address table | `regmap_version=` in the `parameters` of the top node | `regmap_hash=` in the same `parameters` | -| LaTeX documentation | Title page and page footer | Title page, under the version | +| Documentation | Title and page footer (HTML: running header) | Title, under the version | ### Hash and version registers @@ -269,7 +269,7 @@ Each entry in `register` is one register. | `address` | [number](#numbers) | next free address | Register offset. See [Addresses](#addresses). | | `width` | [number](#numbers) | `data_width` | Width of a `vector` register. | | `reset` | [number](#numbers) | `0` | Reset value of a register without fields. See [Reset values](#reset-values). | -| `description` | string | `""` | Shown in the LaTeX documentation and the IPBus address table. | +| `description` | string | `""` | Shown in the documentation and the IPBus address table. | | `fields` | list | none | The fields of a `fields` register. See [Fields](#fields). | | access keys | | | Defaults for the register's fields. See [Access keys](#access-keys). | @@ -438,7 +438,7 @@ A `fields` register lists its fields under `fields`. Each entry is one field. | `width` | [number](#numbers) | `1` | Width of a `vector` field. A `bit` field is always 1 bit wide, and bust ignores a different `width` with a warning. | | `position` | [number](#numbers) | next free bit | Lowest bit of the field. See [Bit positions](#bit-positions). | | `reset` | [number](#numbers) | `0` | Reset value of the field. | -| `description` | string | `""` | Shown in the LaTeX documentation and the IPBus address table. | +| `description` | string | `""` | Shown in the documentation and the IPBus address table. | | `enums` | list | none | Named values. See [Enumerations](#enumerations). | | access keys | | from the register | See [Access keys](#access-keys). | diff --git a/example/example_axi/doc/example_axi.html b/example/example_axi/doc/example_axi.html new file mode 100644 index 00000000..009184e7 --- /dev/null +++ b/example/example_axi/doc/example_axi.html @@ -0,0 +1,216 @@ + + + + + + +example_axi + + + + +
+
Generated by bust v1.0.0-devVersion: 1.0
+
+

example_axi

+

Version: 1.0

+

Register map hash: 0x0CF519FC

+

1970-01-01 00:00

+
+

An example module that contain all the register types that are currently supported by bust.

+ +

1 Register List

+
+ + + + + + + + + + + + + + + + + + + + +
#NameSW/HWAddressTypeWidthReset
0reg0RW/R0x00000000BIT10x0
1reg1RW/R0x00000004BIT10x1
2reg2RO/W0x00000008BIT10x0
3reg3RW/R0x0000000CVECTOR80x3
4reg4RO/W0x00000010VECTOR140x0
5reg5RW/R0x00000014DEFAULT320xFFFFFFFF
6reg6RO/W0x00000018DEFAULT320x0
7reg7RW/R0x0000001CFIELDS210xAD7
8reg8RO/W0x00000020FIELDS240x0
9reg9WO/R0x00000024BIT10x1
10reg10WO/R0x00000028VECTOR40xA
11reg11WO/R0x0000002CFIELDS160x3
12regmap_hashRO/NA0x00000030HASH320xCF519FC
13regmap_versionRO/NA0x00000034VERSION320x10000
+
+ +

2 Registers

+
+

reg0 - RW/R0x00000000

+

RW std_logic register that resets to 0x0

+
311unused-0reg00
+

Back to the register list

+
+
+

reg1 - RW/R0x00000004

+

RW std_logic register that resets to 0x1

+
311unused-0reg11
+

Back to the register list

+
+
+

reg2 - RO/W0x00000008

+

RO std_logic register

+
311unused-0reg20
+

Back to the register list

+
+
+

reg3 - RW/R0x0000000C

+

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

+
318unused-70reg30x3
+

Back to the register list

+
+
+

reg4 - RO/W0x00000010

+

RO std_logic_vector[13:0]

+
3114unused-130reg40x0
+

Back to the register list

+
+
+

reg5 - RW/R0x00000014

+

Default RW register that resets to 0xFFFFFFFF

+
310reg50xFFFFFFFF
+

Back to the register list

+
+
+

reg6 - RO/W0x00000018

+

Default RO register

+
310reg60x0
+

Back to the register list

+
+
+

reg7 - RW/R0x0000001C

+

RW register that have multiple fields

+
3121unused-206field30x2B5field2041field10xB0field01
+
+
field0
std_logic that resets to 0x1 (sw: rw, hw: r)
+
field1
std_logic_vector[3:0] that resets to 0xb is not a valid reset value (sw: rw, hw: r)
+
field2
std_logic that resets to 0x1 (sw: rw, hw: r)
+
field3
std_logic_vector[14:0] that resets to 0x2b (sw: rw, hw: r)
+
+

Back to the register list

+
+
+

reg8 - RO/W0x00000020

+

RO register with multiple types of fields

+
3124unused-2321field30x020field20191field10x00field00
+
+
field0
std_logic field (sw: ro, hw: w)
+
field1
std_logic_vector[18:0] field (sw: ro, hw: w)
+
field2
std_logic field (sw: ro, hw: w)
+
field3
std_logic_vector[2:0] field (sw: ro, hw: w)
+
+

Back to the register list

+
+
+

reg9 - WO/R0x00000024

+

PULSE std_logic register that resets to 0x1

+
311unused-0reg91
+

Back to the register list

+
+
+

reg10 - WO/R0x00000028

+

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

+
314unused-30reg100xA
+

Back to the register list

+
+
+

reg11 - WO/R0x0000002C

+

PULSE register with two fields

+
3116unused-15field10140field00x3
+
+
field0
std_logic_vector[14:0] field that resets to 0x3 (sw: wo, hw: r, singlepulse)
+
field1
std_logic field that resets to 0x0 (sw: wo, hw: r, singlepulse)
+
+

Back to the register list

+
+
+

regmap_hash - RO/NA0x00000030

+

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

+
310regmap_hash0xCF519FC
+

Back to the register list

+
+
+

regmap_version - RO/NA0x00000034

+

Version of the register map, 1.0 as 0x00010000

+
310regmap_version0x10000
+

Back to the register list

+
+
+ + diff --git a/example/example_ipbus/doc/example_ipbus.html b/example/example_ipbus/doc/example_ipbus.html new file mode 100644 index 00000000..99dcfc0d --- /dev/null +++ b/example/example_ipbus/doc/example_ipbus.html @@ -0,0 +1,200 @@ + + + + + + +example_ipbus + + + + +
+
Generated by bust v1.0.0-devVersion: 1.0
+
+

example_ipbus

+

Version: 1.0

+

Register map hash: 0xFCD085B6

+

1970-01-01 00:00

+
+

An example module that contain all the register types that are currently supported by bust.

+ +

1 Register List

+
+ + + + + + + + + + + + + + + + + + +
#NameSW/HWAddressTypeWidthReset
0reg0RW/R0x00000000BIT10x0
1reg1RW/R0x00000004BIT10x1
2reg2RO/W0x00000008BIT10x0
3reg3RW/R0x0000000CVECTOR80x3
4reg4RO/W0x00000010VECTOR140x0
5reg5RW/R0x00000014DEFAULT320xFFFFFFFF
6reg6RO/W0x00000018DEFAULT320x0
7reg7RW/R0x0000001CFIELDS210xAD7
8reg8RO/W0x00000020FIELDS240x0
9reg9WO/R0x00000024BIT10x1
10reg10WO/R0x00000028VECTOR40xA
11reg11WO/R0x0000002CFIELDS160x3
+
+ +

2 Registers

+
+

reg0 - RW/R0x00000000

+

RW std_logic register that resets to 0x0

+
311unused-0reg00
+

Back to the register list

+
+
+

reg1 - RW/R0x00000004

+

RW std_logic register that resets to 0x1

+
311unused-0reg11
+

Back to the register list

+
+
+

reg2 - RO/W0x00000008

+

RO std_logic register

+
311unused-0reg20
+

Back to the register list

+
+
+

reg3 - RW/R0x0000000C

+

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

+
318unused-70reg30x3
+

Back to the register list

+
+
+

reg4 - RO/W0x00000010

+

RO std_logic_vector[13:0]

+
3114unused-130reg40x0
+

Back to the register list

+
+
+

reg5 - RW/R0x00000014

+

Default RW register that resets to 0xFFFFFFFF

+
310reg50xFFFFFFFF
+

Back to the register list

+
+
+

reg6 - RO/W0x00000018

+

Default RO register

+
310reg60x0
+

Back to the register list

+
+
+

reg7 - RW/R0x0000001C

+

RW register that have multiple fields

+
3121unused-206field30x2B5field2041field10xB0field01
+
+
field0
std_logic that resets to 0x1 (sw: rw, hw: r)
+
field1
std_logic_vector[3:0] that resets to 0xb is not a valid reset value (sw: rw, hw: r)
+
field2
std_logic that resets to 0x1 (sw: rw, hw: r)
+
field3
std_logic_vector[14:0] that resets to 0x2b (sw: rw, hw: r)
+
+

Back to the register list

+
+
+

reg8 - RO/W0x00000020

+

RO register with multiple types of fields

+
3124unused-2321field30x020field20191field10x00field00
+
+
field0
std_logic field (sw: ro, hw: w)
+
field1
std_logic_vector[18:0] field (sw: ro, hw: w)
+
field2
std_logic field (sw: ro, hw: w)
+
field3
std_logic_vector[2:0] field (sw: ro, hw: w)
+
+

Back to the register list

+
+
+

reg9 - WO/R0x00000024

+

PULSE std_logic register that resets to 0x1

+
311unused-0reg91
+

Back to the register list

+
+
+

reg10 - WO/R0x00000028

+

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

+
314unused-30reg100xA
+

Back to the register list

+
+
+

reg11 - WO/R0x0000002C

+

PULSE register with two fields

+
3116unused-15field10140field00x3
+
+
field0
std_logic_vector[14:0] field that resets to 0x3 (sw: wo, hw: r, singlepulse)
+
field1
std_logic field that resets to 0x0 (sw: wo, hw: r, singlepulse)
+
+

Back to the register list

+
+
+ + diff --git a/example/example_prototype/doc/prototype.html b/example/example_prototype/doc/prototype.html new file mode 100644 index 00000000..85c0aefe --- /dev/null +++ b/example/example_prototype/doc/prototype.html @@ -0,0 +1,231 @@ + + + + + + +prototype + + + + +
+
Generated by bust v1.0.0-devVersion: 1.0
+
+

prototype

+

Version: 1.0

+

Register map hash: 0x593FA68E

+

1970-01-01 00:00

+
+

Comprehensive example exercising every v1 access mode, mirroring the prototype demo module (reg0..reg11).

+ +

1 Register List

+
+ + + + + + + + + + + + + + + + + + +
#NameSW/HWAddressTypeWidthReset
0reg0RW/R0x00000000FIELDS30x0
1reg1RO/W0x00000004FIELDS60x0
2reg2WO/R0x00000008FIELDS10x0
3reg3RW/NA0x0000000CFIELDS80x0
4reg4RW/RW0x00000010FIELDS90x0
5reg5RW/R0x00000014FIELDS80x0
6reg6RW/R0x00000018FIELDS120xF0
7reg7RW/R0x0000001CFIELDS120xF0
8reg8RW/R0x00000020FIELDS80xF
9reg9RW/R0x00000024FIELDS80x0
10reg10RW/R0x00000028FIELDS40x0
11reg11RW/R0x0000002CFIELDS20x0
+
+ +

2 Registers

+
+

reg0 - RW/R0x00000000

+

Plain rw storage, hardware reads back.

+
313unused-21field10x00field00
+
+
field0
(sw: rw, hw: r)
+
field1
(sw: rw, hw: r)
+
+

Back to the register list

+
+
+

reg1 - RO/W0x00000004

+

Hardware-driven status, software read-only.

+
316unused-5field204field1030field00x0
+
+
field0
(sw: ro, hw: w)
+
field1
(sw: ro, hw: w)
+
field2
(sw: ro, hw: w)
+
+

Back to the register list

+
+
+

reg2 - WO/R0x00000008

+

Write-only command field.

+
311unused-0field00
+
+
field0
(sw: wo, hw: r)
+
+

Back to the register list

+
+
+

reg3 - RW/NA0x0000000C

+

Software-only scratch register.

+
318unused-70field00x0
+
+
field0
(sw: rw, hw: na)
+
+

Back to the register list

+
+
+

reg4 - RW/RW0x00000010

+

Hardware write-enable and hardware set/clear.

+
319unused-8field1074unused-30field00x0
+
+
field0
(sw: rw, hw: rw)
+
field1
(sw: rw, hw: r)
+
+

Back to the register list

+
+
+

reg5 - RW/R0x00000014

+

Read side effects.

+
318unused-74field10x030field00x0
+
+
field0
(sw: rw, hw: r, onread: rclr)
+
field1
(sw: rw, hw: r, onread: rset)
+
+

Back to the register list

+
+
+

reg6 - RW/R0x00000018

+

Write-1 onwrite effects.

+
3112unused-118field20x074field10xF30field00x0
+
+
field0
(sw: rw, hw: r, onwrite: woset)
+
field1
(sw: rw, hw: r, onwrite: woclr)
+
field2
(sw: rw, hw: r, onwrite: wot)
+
+

Back to the register list

+
+
+

reg7 - RW/R0x0000001C

+

Write-0 onwrite effects.

+
3112unused-118field20x074field10xF30field00x0
+
+
field0
(sw: rw, hw: r, onwrite: wzs)
+
field1
(sw: rw, hw: r, onwrite: wzc)
+
field2
(sw: rw, hw: r, onwrite: wzt)
+
+

Back to the register list

+
+
+

reg8 - RW/R0x00000020

+

Whole-field onwrite effects.

+
318unused-74field10x030field00xF
+
+
field0
(sw: rw, hw: r, onwrite: wclr)
+
field1
(sw: rw, hw: r, onwrite: wset)
+
+

Back to the register list

+
+
+

reg9 - RW/R0x00000024

+

Software-access pulses.

+
318unused-74field10x030field00x0
+
+
field0
(sw: rw, hw: r)
+
field1
(sw: rw, hw: r)
+
+

Back to the register list

+
+
+

reg10 - RW/R0x00000028

+

Single-cycle pulse on software write.

+
314unused-30field00x0
+
+
field0
(sw: rw, hw: r, singlepulse)
+
+

Back to the register list

+
+
+

reg11 - RW/R0x0000002C

+

Enumerated field.

+
312unused-10field00x0
+
+
field0
(sw: rw, hw: r; values: STATE0=0, STATE1=1, STATE2=2, STATE3=3)
+
+

Back to the register list

+
+
+ + diff --git a/scripts/smoke-test.sh b/scripts/smoke-test.sh index f5609339..179244ea 100755 --- a/scripts/smoke-test.sh +++ b/scripts/smoke-test.sh @@ -9,6 +9,8 @@ examples="$(cd "$(dirname "$0")/../example" && pwd)" output_dir="$(mktemp -d)" # bust writes debug.log to the working directory. cd "$output_dir" +# The HTML documentation shows the time of the run, which the goldens pin to 0. +export SOURCE_DATE_EPOCH=0 bust --version | grep -Fx "bust v$expected_version" for example in example_axi example_ipbus; do diff --git a/tests/test_generation.py b/tests/test_generation.py index 52aacce2..7200b10b 100644 --- a/tests/test_generation.py +++ b/tests/test_generation.py @@ -1,6 +1,6 @@ """.vhd belongs to the user. bust writes a starter only when the file is missing, does not replace it with -f, and replaces it with --replace-top, keeping -the old file.""" +the old file. The documentation needs no pdflatex.""" import logging import os @@ -30,7 +30,7 @@ def _write_top(out_dir, text): return top -def _generate(out_dir, force_ow=True, replace_top=False): +def _generate(out_dir, force_ow=True, replace_top=False, gen_doc=False): cfg = json_parser(_EXAMPLE_JSON) settings = Settings(_EXAMPLE_JSON) bus = Bus(cfg["bus"]) @@ -38,8 +38,8 @@ def _generate(out_dir, force_ow=True, replace_top=False): "dir": str(out_dir), "force_ow": force_ow, "replace_top": replace_top, - "gen_doc": False, - "gen_pdf": False, + "gen_doc": gen_doc, + "gen_pdf": gen_doc, "gen_header": False, "gen_localbus": True, } @@ -102,3 +102,15 @@ def test_replace_top_without_a_terminal_asks_for_force(tmp_path, monkeypatch): assert _read(top) == "-- my own top level\n" assert not os.path.exists(top + ".bak") + + +def test_docs_without_pdflatex_skip_only_the_pdf(tmp_path, monkeypatch, caplog): + pytest.importorskip("pylatexenc") + monkeypatch.setenv("PATH", str(tmp_path / "empty")) + + with caplog.at_level(logging.INFO): + _generate(tmp_path, gen_doc=True) + + doc_dir = os.path.join(str(tmp_path), "example_axi", "doc") + assert sorted(os.listdir(doc_dir)) == ["example_axi.html", "example_axi.tex"] + assert "pdflatex is not on PATH, so bust skipped the PDF" in caplog.text diff --git a/tests/test_latex.py b/tests/test_latex.py index 95ab94f6..4b319631 100644 --- a/tests/test_latex.py +++ b/tests/test_latex.py @@ -1,4 +1,4 @@ -"""Descriptions in the LaTeX documentation.""" +"""Descriptions in the LaTeX and HTML documentation.""" import pytest @@ -10,3 +10,11 @@ def test_description_code_and_unknown_characters(): assert utf8tolatex("⚠️ Write `ctrl_reg` & 50% é") == ( r" Write \texttt{ctrl{\_}reg} {\&} 50{\%} {\'e}" ) + + +def test_html_description_escapes_and_keeps_code(): + from bust.jinja_utils.filters import utf8tohtml + + assert utf8tohtml("⚠️ Write `a") == ( + "⚠️ Write a<b & <i>" + ) diff --git a/tests/test_suite.py b/tests/test_suite.py index a852ca51..c1025203 100644 --- a/tests/test_suite.py +++ b/tests/test_suite.py @@ -173,13 +173,17 @@ def test_doc(self): for holder in self.buzz: with self.subTest(holder=holder): self.logger.info("Testing Doc generation...") + base = "example/example_{0}/doc/example_{0}".format(holder.bus.bus_type) self._assert_matches( holder.doc.generate_tex_documentation("1.0.0-dev"), - "example/example_{0}/doc/example_{0}.tex".format( - holder.bus.bus_type - ), + base + ".tex", "doc must match manual file", ) + self._assert_matches( + holder.doc.generate_html_documentation("1.0.0-dev"), + base + ".html", + "html doc must match manual file", + ) ############## Prototype (full access-mode coverage) ################## @@ -342,6 +346,11 @@ def test_prototype_doc(self): "example/example_prototype/doc/prototype.tex", "prototype doc must match manual file", ) + self._assert_matches( + doc.generate_html_documentation("1.0.0-dev"), + "example/example_prototype/doc/prototype.html", + "prototype html doc must match manual file", + ) ############## Access-mode combination matrix ##################