67 lines
2.5 KiB
Markdown
67 lines
2.5 KiB
Markdown
# hexdoc
|
|
|
|
This is the Python docgen for Hex Casting.
|
|
|
|
## Version scheme
|
|
|
|
We use [hatch-gradle-version](https://pypi.org/project/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:
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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:
|
|
```sh
|
|
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:
|
|
```sh
|
|
# 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:
|
|
```sh
|
|
hexdoc serve doc/properties.toml --src _site/src/docs --dst _site/dst/docs
|
|
```
|