Python web book docgen for Patchouli and Hex Casting.

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

object-Object

These details have not been verified by PyPI

Project links

Project description

hexdoc logo

PyPI - Python Version

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

[![hexdoc](https://img.shields.io/endpoint?url=https://hexxy.media/api/v0/badge/hexdoc)](https://github.com/hexdoc-dev/hexdoc)

[![powered by hexdoc](https://img.shields.io/endpoint?url=https://hexxy.media/api/v0/badge/hexdoc?label=1)](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>

Project details

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

object-Object

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

This version

1!0.1.0a26 pre-release

May 12, 2025

1!0.1.0a25 pre-release

Apr 13, 2025

1!0.1.0a24 pre-release

Mar 30, 2025

1!0.1.0a23 pre-release

Feb 24, 2025

1!0.1.0a22 pre-release

Feb 23, 2025

1!0.1.0a21 pre-release

Oct 26, 2024

1!0.1.0a20 pre-release

Sep 8, 2024

1!0.1.0a19 pre-release

Jun 11, 2024

1!0.1.0a18 pre-release

Jun 9, 2024

1!0.1.0a17 pre-release

May 24, 2024

1!0.1.0a16 pre-release

May 4, 2024

1!0.1.0a15 pre-release

May 2, 2024

1!0.1.0a14 pre-release

May 1, 2024

1!0.1.0a13 pre-release

Apr 27, 2024

1!0.1.0a12 pre-release

Apr 7, 2024

1!0.1.0a11 pre-release

Mar 30, 2024

1!0.1.0a10 pre-release

Feb 23, 2024

1!0.1.0a10.dev0 pre-release

Jan 5, 2024

1!0.1.0a9 pre-release

Jan 1, 2024

1!0.1.0a8 pre-release

Dec 30, 2023

1!0.1.0a7 pre-release

Dec 20, 2023

1!0.1.0a6 pre-release

Dec 17, 2023

1!0.1.0a5 pre-release

Dec 17, 2023

1!0.1.0a4 pre-release

Dec 16, 2023

1!0.1.0a3 pre-release

Dec 14, 2023

1!0.1.0a2 pre-release

Dec 10, 2023

1!0.1.0a2.dev0 pre-release

Dec 10, 2023

1!0.1.0a1 pre-release

Dec 4, 2023

1!0.1.0a0 pre-release

Dec 2, 2023

1!0.1.0.dev7 pre-release

Dec 2, 2023

1!0.1.0.dev6 pre-release

Nov 30, 2023

1!0.1.0.dev5 pre-release

Nov 24, 2023

1!0.1.0.dev4 pre-release

Nov 23, 2023

1!0.1.0.dev3 pre-release

Nov 23, 2023

1!0.1.0.dev2 pre-release

Nov 22, 2023

1!0.1.0.dev1 pre-release yanked

Nov 21, 2023