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.
| Light Mode (default, black stroke) | Dark Mode (white stroke) |
|---|---|
 |
 |
 |
 |
 |
 |
| 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.
pip install sphinxcontrib-archwareThen add the extension to conf.py:
extensions = ["sphinxcontrib.archware"]The extension requires a TeX installation with the bytefield and register
LaTeX packages, and a tool to convert the compiled output to SVG.
# 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# 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 lmInstall 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.
latex --version # should print a LaTeX version string
dvisvgm --version # should print a dvisvgm version stringPackage-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"This package was developed interactively with Claude (Anthropic) as a coding and documentation assistant. All output was reviewed and directed by the author.