History

gamma_02 284ee22e4d Added isometric renders of block models rendered in-game try #2 with funny pan		2023-10-12 17:19:22 -07:00
..
src/hexdoc	Added isometric renders of block models rendered in-game try #2 with funny pan	2023-10-12 17:19:22 -07:00
static	Add optional static dir	2023-08-27 19:14:01 -04:00
test	Refactor most of the core logic out of utils	2023-10-10 00:58:55 -04:00
{{cookiecutter.output_directory}}	Update command examples in READMEs	2023-09-30 02:08:31 -04:00
cookiecutter.json	Remove base_asset_urls	2023-09-29 02:18:09 -04:00
LICENSE.txt	Add more metadata	2023-09-17 17:42:28 -04:00
nodemon.json	Improve watch mode behaviour	2023-10-09 20:35:13 -04:00
properties.toml	Remove colorizers from allowed missing textures	2023-10-09 16:09:58 -04:00
README.md	Update command examples in READMEs	2023-09-30 02:08:31 -04:00

README.md

hexdoc

This is the Python docgen for Hex Casting.

Version scheme

We use hatch-gradle-version to generate the version number based on whichever mod version the docgen was built with.

The version is in this format: mod-version.python-version.mod-pre.python-dev.python-post

For example:

Mod version: 0.11.1-7
Python package version: 1.0.dev0
Full version: 0.11.1.1.0rc7.dev0

Creating a plugin / addon

WIP.

Run these commands, then follow the prompts:
```
pip install cookiecutter
cookiecutter gh:object-Object/HexMod --directory doc
```
- Note: if you run this from within an existing mod repo, add the flag -f and leave output_directory blank.
Fill in the TODOs in doc/properties.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 to Deploy from a branch, the branch to gh-pages, and the folder to docs/.
Commit and push the docgen, and see if the CI works.
On GitHub, under Settings > Environments, create two new environments called pypi and testpypi.
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 the TestPyPI release choice from your workflow without impacting the rest of the CI.

Setup

python -m venv venv

.\venv\Scripts\activate  # Windows
source venv/bin/activate # anything other than Windows

# run from the repo root, not doc/
pip install -e .[dev]

Usage

For local testing, create a file called .env following this template:

GITHUB_REPOSITORY=gamma-delta/HexMod
GITHUB_SHA=main
GITHUB_PAGES_URL=https://gamma-delta.github.io/HexMod

Then run these commands to generate the book:

# run from the repo root, not doc/
hexdoc render doc/properties.toml _site/src/docs
hexdoc merge --src _site/src/docs --dst _site/dst/docs

Or, run this command to render the book and start a local web server:

hexdoc serve doc/properties.toml --src _site/src/docs --dst _site/dst/docs