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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file hexdoc-1!0.1.0a40.tar.gz.
File metadata
- Download URL: hexdoc-1!0.1.0a40.tar.gz
- Upload date:
- Size: 155.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
aaaf169a949cf03b11607c94fc239ffc9c45673364d80bdcd56413ce1d471309
|
|
| MD5 |
a083786786d0341a1fe82ef36cb14a25
|
|
| BLAKE2b-256 |
5a2ce7dcc914cda4a515e3d952b56ce503b697eae51a55f10e2dc9e95f6920a8
|
Provenance
The following attestation bundles were made for hexdoc-1!0.1.0a40.tar.gz:
Publisher:
ci.yml on hexdoc-dev/hexdoc
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
hexdoc-1!0.1.0a40.tar.gz -
Subject digest:
aaaf169a949cf03b11607c94fc239ffc9c45673364d80bdcd56413ce1d471309 - Sigstore transparency entry: 1810717426
- Sigstore integration time:
-
Permalink:
hexdoc-dev/hexdoc@e37c5d449995dd1f84b43079b91dfcca78a6fdde -
Branch / Tag:
refs/tags/v1!0.1.0a40 - Owner: https://github.com/hexdoc-dev
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
ci.yml@e37c5d449995dd1f84b43079b91dfcca78a6fdde -
Trigger Event:
push
-
Statement type:
File details
Details for the file hexdoc-1!0.1.0a40-py3-none-any.whl.
File metadata
- Download URL: hexdoc-1!0.1.0a40-py3-none-any.whl
- Upload date:
- Size: 225.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
995dac6587475bc267ccedbb1b0d323fab2fd1d40968bcd847517a2d8490674f
|
|
| MD5 |
596090877c3c5860b1142782323fa1ef
|
|
| BLAKE2b-256 |
b412a26fac83f51d2d97ff36c917b1e0380adfb3217ed5083ed4689e1188fad7
|
Provenance
The following attestation bundles were made for hexdoc-1!0.1.0a40-py3-none-any.whl:
Publisher:
ci.yml on hexdoc-dev/hexdoc
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
hexdoc-1!0.1.0a40-py3-none-any.whl -
Subject digest:
995dac6587475bc267ccedbb1b0d323fab2fd1d40968bcd847517a2d8490674f - Sigstore transparency entry: 1810717443
- Sigstore integration time:
-
Permalink:
hexdoc-dev/hexdoc@e37c5d449995dd1f84b43079b91dfcca78a6fdde -
Branch / Tag:
refs/tags/v1!0.1.0a40 - Owner: https://github.com/hexdoc-dev
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
ci.yml@e37c5d449995dd1f84b43079b91dfcca78a6fdde -
Trigger Event:
push
-
Statement type:
