Backport the hexdoc-hexcasting web book to 1.18

.github/workflows/build_docs.yml

@@ -1,29 +1,60 @@
-name: Build the Python doc-gen
+name: Build the web book
 
 on:
   push:
-    branches: [main]
+    branches: '1.18'
+  workflow_dispatch:
+    inputs:
+      release:
+        description: Release this version
+        type: boolean
+        default: false
+      publish:
+        description: Package index to publish to
+        type: choice
+        options:
+          - none
+          - PyPI
+
+env:
+  PYPI_PACKAGE: hexdoc-hexcasting
+
+permissions:
+  contents: read
 
 jobs:
-  build_docs:
-    runs-on: ubuntu-latest
+  hexdoc:
+    uses: hexdoc-dev/hexdoc/.github/workflows/hexdoc.yml@main
     permissions:
       contents: write
+      pages: read
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    with:
+      python-version: "3.11"
+      release: |-
+        ${{
+          github.event_name != 'push' && inputs.release
+          || github.event_name == 'push' && startsWith(github.event.head_commit.message, '[Release]')
+        }}
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    needs: hexdoc
+    if: |-
+      needs.hexdoc.outputs.release == 'true' &&
+      (github.event_name == 'push' || inputs.publish == 'PyPI')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ env.PYPI_PACKAGE }}
+    permissions:
+      id-token: write
     steps:
-    - uses: actions/checkout@v3
-    - name: Generate file
-      run: doc/collate_data.py Common/src/main/resources hexcasting thehexbook doc/template.html index.html.uncommitted
-    - name: Check out gh-pages
-      uses: actions/checkout@v3
-      with:
-        clean: false
-        ref: gh-pages
-    - name: Overwrite file and commmit
-      run: |
-          mv index.html.uncommitted index.html
-          git config user.name "Documentation Generation Bot"
-          git config user.email "[email protected]"
-          git add index.html
-          git diff-index --quiet HEAD || git commit -m "Update docs at index.html from $GITHUB_REF"
-    - name: Upload changes
-      run: git push
+      - name: Download package artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: hexdoc-build
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -1,3 +1,10 @@
+# hexdoc
+doc/**/_export/generated/
+/_site/
+/_checkout/
+__gradle_version__.py
+.hexdoc/
+
 # eclipse
 bin
 *.launch
@@ -21,9 +28,168 @@ build
 eclipse
 run
 
+# MacOS moment
+.DS_Store
+
 # Files from Forge MDK
 forge*changelog.txt
 
 Session.vim
 plot/
 
+
+# Python
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/

Common/src/main/resources/assets/hexcasting/lang/ru_ru.json

@@ -802,7 +802,7 @@
 	"_comment": "Продвинутые руны",
 
 	"hexcasting.entry.itempicking": "Работа с предметами",
-	"hexcasting.page.itempicking.1": "Некоторые руны, такие как $(l:hexcasting:patterns/spells/blockworks#OpPlaceBlock)$(action)Поставить блок/$, потребляют дополнительные предметы из инвентаря. Руна ищёт предмет для использования.",
+	"hexcasting.page.itempicking.1": "Некоторые руны, такие как $(l:hexcasting:patterns/spells/blockworks#hexcasting:place_block)$(action)Поставить блок/$, потребляют дополнительные предметы из инвентаря. Руна ищёт предмет для использования.",
 	"hexcasting.page.itempicking.2": "$(li)Сначала, руна ищёт первый подходящий предмет в хотбаре около $(italic)Посоха/$.$(li)Во вторых, руна использует $(italic)самый далёкий предмет из инвентаря/$.",
 	"hexcasting.page.itempicking.3": "Так можно выбрать какой предмет какое заклинание будет использовать.",
 
@@ -867,7 +867,7 @@
 	"hexcasting.page.flight.1": "The power of flight! I have wrestled Nature to its knees. But Nature is vengeful, and itches for me to break its contract so it may break my shins.",
 	"hexcasting.page.flight.2": "The entity (which must be a player) will be endowed with flight. The first number is the number of seconds they may fly for, and the second number is the radius of the zone they may fly in. If the recipient exits that zone, or their timer runs out while midair, the gravity that they spurned will get its revenge. Painfully.$(br2)It costs approximately 1 $(item)Amethyst Dust/$ multiplied by the radius, per second of flight.",
 
-	"hexcasting.page.teleport.1": "Куда мощнее $(l:patterns/spells/basic#OpBlink)$(action)Блинка/$, это позволит мне телепортироваться на невероятные расстония, пускай ограничение и есть, но оно $(italic)куда больше/$.",
+	"hexcasting.page.teleport.1": "Куда мощнее $(l:patterns/spells/basic#hexcasting:blink)$(action)Блинка/$, это позволит мне телепортироваться на невероятные расстония, пускай ограничение и есть, но оно $(italic)куда больше/$.",
 	"hexcasting.page.teleport.2": "The entity will be teleported by the given vector, which is an offset from its given position. No matter the distance, it always seems to cost about ten $(item)Charged Crystal/$s.$(br2)The transference is not perfect, and it seems when teleporting something as complex as a player, their inventory doesn't $(italic)quite/$ stay attached, and tends to splatter everywhere at the destination.",
 
 	"hexcasting.entry.zeniths": "Zeniths",
@@ -878,7 +878,7 @@
 	"hexcasting.page.zeniths.5": "Bestows haste. Base cost is one $(item)Amethyst Dust/$ per 3 seconds.",
 	"hexcasting.page.zeniths.6": "Bestows strength. Base cost is one $(item)Amethyst Dust/$ per 3 seconds.",
 
-	"hexcasting.page.greater_sentinel.1": "Summon a greater version of my $(l:patterns/sentinels)$(thing)Sentinel/$. Costs about 2 $(item)Amethyst Dust/$s.",
+	"hexcasting.page.greater_sentinel.1": "Summon a greater version of my $(l:patterns/spells/sentinels)$(thing)Sentinel/$. Costs about 2 $(item)Amethyst Dust/$s.",
 	"hexcasting.page.greater_sentinel.2": "The stronger sentinel acts like the normal one I can summon without the use of a Great Spell, if a little more visually interesting. However, the range in which my spells can work is extended to a small region around my greater sentinel, about 16 blocks. In other words, no matter where in the world I am, I can interact with things around my sentinel (the mysterious forces of chunkloading notwithstanding).",
 
 	"hexcasting.page.make_battery.1": "Infuse a bottle with _media to form a $(item)Phial./$",

Common/src/main/resources/data/hexcasting/patchouli_books/thehexbook/en_us/categories/greatwork.json

@@ -2,6 +2,5 @@
   "name": "hexcasting.entry.greatwork",
   "description": "hexcasting.entry.greatwork.desc",
   "icon": "minecraft:music_disc_11",
-  "sortnum": 3,
-  "entry_color": "54398a"
+  "sortnum": 3
 }

Common/src/main/resources/data/hexcasting/patchouli_books/thehexbook/en_us/entries/patterns/great_spells/greater_sentinel.json

@@ -9,6 +9,7 @@
     {
       "type": "hexcasting:pattern",
       "op_id": "hexcasting:sentinel/create/great",
+      "anchor": "hexcasting:sentinel/create/great",
       "text": "hexcasting.page.greater_sentinel.1",
       "input": "vector",
       "output": ""

Common/src/main/resources/data/hexcasting/patchouli_books/thehexbook/en_us/entries/patterns/great_spells/zeniths.json

@@ -3,7 +3,7 @@
   "category": "hexcasting:patterns/great_spells",
   "icon": "minecraft:potion{Potion:'minecraft:regeneration'}",
   "advancement": "hexcasting:root",
-  "sort_num": 4,
+  "sortnum": 4,
   "read_by_default": true,
   "pages": [
     {

doc/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 object-Object, Alwinfy, gamma-delta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

doc/README.md

@@ -0,0 +1,56 @@
+# hexdoc-hexcasting
+
+Python web book docgen and [hexdoc](https://pypi.org/project/hexdoc) plugin 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`
+
+## Setup
+
+```sh
+python3.11 -m venv venv
+
+.\venv\Scripts\activate   # Windows
+. venv/bin/activate.fish  # fish
+source venv/bin/activate  # everything else
+
+# run from the repo root, not doc/
+pip install -e .[dev]
+```
+
+## Usage
+
+For local testing, create a file called `.env` in the repo root following this template:
+```sh
+GITHUB_REPOSITORY=gamma-delta/HexMod
+GITHUB_SHA=main
+GITHUB_PAGES_URL=https://gamma-delta.github.io/HexMod
+```
+
+Useful commands:
+```sh
+# show help
+hexdoc -h
+
+# render and serve the web book in watch mode
+nodemon --config doc/nodemon.json
+
+# 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
+```