Metadata-Version: 2.4
Name: sphinxcontrib-archware
Version: 0.0.1
Summary: Sphinx extension to render bytefield and register hardware diagrams as SVG.
License: MIT
License-File: LICENSE
Keywords: sphinx,bytefield,register,memory,cpu,architecture,hardware
Author: Aras Ashraf Gandomi
Author-email: aras.gandomi@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: sphinx (>=5.0)
Requires-Dist: sphinx-rtd-theme (>=3.1.0,<4.0.0)
Project-URL: Documentation, https://sphinxcontrib-archware.readthedocs.io
Project-URL: Homepage, https://AAGandomi.github.io/sphinxcontrib-archware/
Project-URL: Issues, https://github.com/AAGandomi/sphinxcontrib-archware/issues
Project-URL: Repository, https://github.com/AAGandomi/sphinxcontrib-archware
Description-Content-Type: text/markdown

# sphinxcontrib-archware

A Sphinx extension for documenting digital hardware in RST.

It provides directives for rendering
[`bytefield`](https://ctan.org/pkg/bytefield) packet and register diagrams
and [`register`](https://ctan.org/pkg/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

```bash
pip install sphinxcontrib-archware
```

Then add the extension to `conf.py`:

```python
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

```bash
# 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)

```bash
# 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](https://miktex.org/download).  The `bytefield` and
`register` packages will be downloaded automatically on first use.
Install `dvisvgm` via the MiKTeX package manager, or install
[Inkscape](https://inkscape.org/) as the SVG converter.

### Verifying the installation

```bash
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:

```python
# 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](https://claude.ai)
> (Anthropic) as a coding and documentation assistant. All output was
> reviewed and directed by the author.

