hexdoc

A Jinja-based documentation generator for Patchouli books.

This is the library that powers Hex Casting's web book.

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
Node.js 20+: https://github.com/stackgl/headless-gl/issues/268

hexdoc is known to work with Python 3.11 and Node.js 18.

Plugins

See hexdoc-hexcasting-template for instructions to set up a hexdoc plugin for a pre-existing Hex Casting addon.

Contributing

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

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>

Metadata

Release files for hexdoc 1!0.1.0a10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hexdoc 1!0.1.0a10
File	Size	Uploaded
hexdoc-1!0.1.0a10.tar.gz	129.4 kB	Feb 23, 2024	Details

Built distribution (wheel)

Table of built distributions (wheels) for hexdoc 1!0.1.0a10
File	Interpreter	ABI	Platform	Reset
hexdoc-1!0.1.0a10-py3-none-any.whl 189.2 kB Feb 23, 2024	Python 3	none	any	Details

Total release size: 318.7 kB

Release files / hexdoc-1!0.1.0a10.tar.gz

Download URL	hexdoc-1!0.1.0a10.tar.gz
Size	129.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`b4b38a42cd9b47537be4449c07d848eab1cf63ae36d07594cec313e6d3b3f763`
BLAKE2b-256 checksum How to use checksums	`9b6de62be057290b1972afa131e257d8c5730b6a8754b3f140f79714d10b3489`
Upload date	Feb 23, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/4.0.2 CPython/3.11.8`

Release files / hexdoc-1!0.1.0a10-py3-none-any.whl

Download URL	hexdoc-1!0.1.0a10-py3-none-any.whl
Size	189.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`410f36a9eeeb45811cbf59760fc4d6a51ad0794e525426f2564d7c1c73d26b80`
BLAKE2b-256 checksum How to use checksums	`935de7b96b0153e218631b37bafde8bda0723f80384e105d3913f2711142d10d`
Upload date	Feb 23, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/4.0.2 CPython/3.11.8`