This release is a pre-release and may not be stable for production use.
hexdoc
A Jinja-based documentation generator for Patchouli books.
This is the library that powers Hex Casting's web book.
Check out the docs at https://hexdoc.hexxy.media!
IMPORTANT: Version incompatibilities
There are issues related to installing hexdoc with the following dependency versions:
- Python 3.12+ on Windows: https://github.com/aio-libs/multidict/issues/887
hexdoc is known to work with Python 3.11.
Plugins
hexdoc has a few Copier templates that you can use to set up a hexdoc plugin for your mod:
- hexdoc-mod-template: generic template
- hexdoc-hexcasting-template: Hex Casting addons (also compatible with HexDummy!)
Support
hexdoc does not currently have a dedicated support server. If you have any questions, please feel free to join the Hex Casting Discord server and ask in the #hexdoc channel, or open an issue/discussion on GitHub.
Contributing
Setup
Automatically set up a development environment with Nox:
pipx install nox # pipx (recommended)
python3 -m pip install nox # pip
nox -s setup
# next, run the venv activation command printed by uv
Manual setup:
git submodule update --init
python3.11 -m venv venv
.\venv\Scripts\activate # Windows
. venv/bin/activate.fish # fish
source venv/bin/activate # everything else
pip install -e .[dev]
pre-commit install
Usage
For local testing, create a file called .env in the repo root following this template:
GITHUB_SHA=main
GITHUB_REPOSITORY=hexdoc-dev/hexdoc
GITHUB_PAGES_URL=https://hexdoc.hexxy.media
Useful commands:
# show help
hexdoc -h
# serve hexdoc resources locally
# this is useful if serving other books locally that depend on hexdoc resources
nodemon --exec "hexdoc serve --port 8001 --no-merge"
# render and serve the Hex Casting web book in watch mode
nodemon
# start the Python interpreter with some extra local variables
hexdoc repl
# run tests
pytest # fast, skips Cookiecutter
nox # slow, full test suite in an isolated venv
nox --no-install # after the first Nox run, use this to skip reinstalling everything
# update test snapshots (only running sessions with the tag "test")
nox -t test -- --snapshot-update
# run hexdoc commands in an isolated environment to ensure it works on its own
nox -s hexdoc -- build
nox -s hexdoc -- repl
# set up a dummy book for local testing
nox -s dummy_setup
nox -s dummy_serve
nox -s dummy_hexdoc -- build
nox -s dummy_clean
# generate and run the full docs website locally, or just run Docusaurus
nox -t docs
nox -s docusaurus
Badges
Shields.io
Markdown
[](https://github.com/hexdoc-dev/hexdoc)
[](https://github.com/hexdoc-dev/hexdoc)
HTML
<a href="https://github.com/hexdoc-dev/hexdoc"><img src="https://img.shields.io/endpoint?url=https://hexxy.media/api/v0/badge/hexdoc" alt="hexdoc" style="max-width:100%;"></a>
<a href="https://github.com/hexdoc-dev/hexdoc"><img src="https://img.shields.io/endpoint?url=https://hexxy.media/api/v0/badge/hexdoc?label=1" alt="powered by hexdoc" style="max-width:100%;"></a>
reStructuredText
.. image:: https://img.shields.io/endpoint?url=https://hexxy.media/api/v0/badge/hexdoc
:target: https://github.com/hexdoc-dev/hexdoc
:alt: hexdoc
.. image:: https://img.shields.io/endpoint?url=https://hexxy.media/api/v0/badge/hexdoc?label=1
:target: https://github.com/hexdoc-dev/hexdoc
:alt: powered by hexdoc
Devin's Badges
Thanks to Sam for making these!
HTML
<a target="_blank" href="INSERT_YOUR_BOOK_LINK_HERE"><img src="https://github.com/SamsTheNerd/HexGloop/blob/73ea39b3becd/externalassets/hexdoc-badgecozy.svg?raw=true" alt="A badge for hexdoc in the style of Devins Badges" width=225></a>
<a target="_blank" href="https://addons.hexxy.media" height=75><img src="https://github.com/SamsTheNerd/HexGloop/blob/73ea39b3becd/externalassets/addon-badge-cozy.svg?raw=true" alt="A badge for addons.hexxy.media in the style of Devins Badges" width=200></a>
1 maintainer
Metadata
1 maintainer
Release files for hexdoc 2.0.0rc1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| hexdoc-2.0.0rc1.tar.gz | 148.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hexdoc-2.0.0rc1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 366.0 kB
Release files / hexdoc-2.0.0rc1.tar.gz
| Download URL | hexdoc-2.0.0rc1.tar.gz |
|---|---|
| Size | 148.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
158b9b5d6a6b71b5208188a08d50e82c5127b0c99d1a0da710297473225665ea
|
|
BLAKE2b-256 checksum How to use checksums |
de9cbeb8b692cc6a68c6a48e4945504bd1fa8355afc7fb4b97330ff8f36d2701
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / hexdoc-2.0.0rc1-py3-none-any.whl
| Download URL | hexdoc-2.0.0rc1-py3-none-any.whl |
|---|---|
| Size | 217.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d2af547873311ce401cc32e3f96d2ec843600d022ddcb5e7cd44cfab4353b089
|
|
BLAKE2b-256 checksum How to use checksums |
452d7128fc304dd7765cbb770687e640d068b2cb88660b629ba1fa2171ae7e3e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency log
