sphinxcontrib-archware 0.0.1

Sphinx extension to render bytefield and register hardware diagrams as SVG.

sphinxcontrib-archware

A Sphinx extension for documenting digital hardware in RST.

It provides directives for rendering bytefield packet and register diagrams and register hardware register diagrams as inline SVG in HTML output, and as native LaTeX floats in PDF output.

Directives

Directive	Description
.. bytefield::	Packet / bit-field diagram
.. register::	Hardware register diagram with rotated field names and reset values
.. regdesc::	Field descriptions as searchable HTML text
.. listofregisters::	Auto-generated list of all register diagrams

Custom commands \colorbitbox, \bitlabel, \rotbitheader, \memsection, and \descbox are always available in every .. bytefield:: directive with no extra configuration.

Installing the Python package

pip install sphinxcontrib-archware

Then add the extension to conf.py:

extensions = ["sphinxcontrib.archware"]

Installing the required TeX tools

The extension requires a TeX installation with the bytefield and register LaTeX packages, and a tool to convert the compiled output to SVG.

Debian / Ubuntu

# TeX Live with the required LaTeX packages
sudo apt install texlive-latex-extra texlive-pictures texlive-science

# SVG converter — dvisvgm is included in texlive-base;
# install inkscape as an alternative if preferred
sudo apt install dvisvgm        # recommended
# or
sudo apt install inkscape

macOS (Homebrew)

# MacTeX includes all required LaTeX packages and dvisvgm
brew install --cask mactex

# or the smaller BasicTeX distribution, then add the missing packages:
brew install --cask basictex
sudo tlmgr update --self
sudo tlmgr install bytefield register standalone lm

Windows (MiKTeX)

Install MiKTeX. The bytefield and register packages will be downloaded automatically on first use. Install dvisvgm via the MiKTeX package manager, or install Inkscape as the SVG converter.

Verifying the installation

latex  --version      # should print a LaTeX version string
dvisvgm --version     # should print a dvisvgm version string

Global package options

Package-level options for the LaTeX packages can be set globally in conf.py and apply to every diagram in the document:

# options forwarded to \usepackage[…]{bytefield}
bytefield_package_options = "bitheight=6ex"

# options forwarded to \usepackage[…]{register}
register_package_options = "botcaption"

Development note

This package was developed interactively with Claude (Anthropic) as a coding and documentation assistant. All output was reviewed and directed by the author.