hexdoc 1!0.1.0a2.dev0

Python web book docgen for Patchouli and Hex Casting.

hexdoc

A Jinja-based documentation generator for Patchouli books.

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

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

# render and serve the web book in watch mode
nodemon

# render and serve the web book
hexdoc serve

# export, render, and merge the web book
hexdoc export
hexdoc render
hexdoc merge

# 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
nox -- --snapshot-update

# run hexdoc commands in an isolated environment to ensure it works on its own
nox -s hexdoc -- export
nox -s hexdoc -- repl