Python web book docgen for Patchouli and Hex Casting.
Project description
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>
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
hexdoc-1!0.1.0a10.tar.gz
(129.4 kB
view hashes)
Built Distribution
hexdoc-1!0.1.0a10-py3-none-any.whl
(189.2 kB
view hashes)
Close
Hashes for hexdoc-1!0.1.0a10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 410f36a9eeeb45811cbf59760fc4d6a51ad0794e525426f2564d7c1c73d26b80 |
|
MD5 | cd2ccd75a99545ea1de598532b136bc1 |
|
BLAKE2b-256 | 935de7b96b0153e218631b37bafde8bda0723f80384e105d3913f2711142d10d |