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.
Plugins
Creating a plugin / addon
WIP.
- Run these commands, then follow the prompts:
pip3 install cruft cruft create https://github.com/object-Object/hexdoc
--directory doc
tells Cookiecutter to look for a template in thedoc
directory of hexdoc, and cannot be omitted.- If you run this from within an existing mod repo, add the flag
-f
, and leave theoutput_directory
option blank when prompted by Cookiecutter.- Note: this currently overwrites any conflicting files, including your .gitignore, so you may need to use your Git history to re-add anything not covered by the new file.
- Fill in the TODOs in
doc/hexdoc.toml
(mostly paths to files/folders in your mod so hexdoc can find the data it needs). - Try running the docgen locally by following the instructions in
doc/README.md
. - If it doesn't already exist, create an empty
gh-pages
branch and push it. - On GitHub, under
Settings > Pages
, set the source toDeploy from a branch
, the branch togh-pages
, and the folder todocs/
. - Commit and push the docgen, and see if the CI works.
- On GitHub, under
Settings > Environments
, create two new environments calledpypi
andtestpypi
. - Follow these instructions for PyPI and TestPyPI: https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/
- TestPyPI is a duplicate of PyPI which can be used for testing package publishing without affecting the real index. The CI workflow includes a manual execution option to publish to TestPyPI.
- If you like to live dangerously, this step is optional - you can remove the
publish-testpypi
job and theTestPyPI
release choice from your workflow without impacting the rest of the CI.
Updating to the latest Cookiecutter template
Run this command: cruft update
See also: https://cruft.github.io/cruft/#updating-a-project
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=object-Object/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
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.0.dev4.tar.gz
(94.4 kB
view hashes)
Built Distribution
hexdoc-1!0.1.0.dev4-py3-none-any.whl
(136.6 kB
view hashes)
Close
Hashes for hexdoc-1!0.1.0.dev4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 02dbfad646a4fb05431e5bd01d6c1bd936f0ce83cc9ec4ce696dd4e28a17d180 |
|
MD5 | 3a41d0b894b9d2031aca75f2816eccbc |
|
BLAKE2b-256 | e7133f5dbd91a8fb9c3a11a4519996d96860049a35d09d0a394e9657ecc2b1c5 |