Metadata-Version: 2.4
Name: sphinxcontrib-hexdump
Version: 0.1.1
Summary: Sphinx directive to render deterministic monochrome hexdumps from binary files
Author: sphinxcontrib-hexdump contributors
License: MIT
Project-URL: Homepage, https://github.com/idduarte/sphinxcontrib-hexdump
Project-URL: Repository, https://github.com/idduarte/sphinxcontrib-hexdump
Project-URL: Issues, https://github.com/idduarte/sphinxcontrib-hexdump/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sphinx>=6.2
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Dynamic: license-file

# sphinxcontrib-hexdump

`sphinxcontrib-hexdump` is a Sphinx extension that renders files as classic monochrome hexdumps using a reStructuredText directive.

## Features

- Reads any file type as raw binary bytes.
- Produces deterministic output with pure Python formatting.
- Emits a single literal code block that works consistently in HTML and LaTeX builders.
- Supports offset/length/line limiting for large files.

## Installation

```bash
pip install sphinxcontrib-hexdump
```

For local development:

```bash
pip install -e .[test]
```

## Enable the extension

Add to `conf.py`:

```python
extensions = [
    "sphinxcontrib.hexdump",
]
```

## Directive usage

```rst
.. hexdump:: ../artifacts/firmware.elf
   :bytes-per-line: 16
   :start: 0
   :length: 256
   :max-lines: 64
```

Lowercase bytes are optional:

```rst
.. hexdump:: ../artifacts/firmware.elf
   :lowercase:
```

## Example output

```text
00000000  48 65 6C 6C 6F 2C 20 68  65 78 64 75 6D 70 21 0A  Hello, hexdump!.
```

## Options

- `:bytes-per-line:` integer >= 1, default `16`
- `:lowercase:` flag; if present, byte hex values are lowercase (default is uppercase)
- `:start:` integer >= 0, default `0`
- `:length:` integer >= 0, default `0` (read until EOF)
- `:max-lines:` integer >= 0, default `0` (no line limit)

## Notes

- Paths are resolved relative to the Sphinx source directory (`env.srcdir`).
- Files outside the docs directory are allowed if they exist.
- For very large files, prefer `:length:` and/or `:max-lines:` to keep output size bounded.

## Release

- TestPyPI and PyPI publishing workflows are included in `.github/workflows/`.
- Full release steps are documented in `PUBLISHING.md`.

## Compatibility

- Python 3.10+
- Sphinx 6.2+

## License

MIT
