sphinxcontrib-hexdump 0.1.1

Sphinx directive to render deterministic monochrome hexdumps from binary files

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

pip install sphinxcontrib-hexdump

For local development:

pip install -e .[test]

Enable the extension

Add to conf.py:

extensions = [
    "sphinxcontrib.hexdump",
]

Directive usage

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

Lowercase bytes are optional:

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

Example output

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