/hexdoc-hexcasting-template

Copier template for adding a hexdoc plugin to a Hex Casting addon.

Primary LanguageJinjaMIT LicenseMIT

hexdoc-hexcasting-template

Copier template for adding a hexdoc plugin to a Hex Casting addon.

Setting up a new plugin for an existing mod

Copying the template

  • Install Python 3.11.
  • Install Copier: pip install pipx && pipx install copier
  • In your repo, copy the template: copier copy gh:hexdoc-dev/hexdoc-hexcasting-template . --overwrite
  • Use your editor's Git diff tool to review any files overwritten by the template (eg. .gitignore).
    • All of the files in the template are there for good reasons, but you might want to merge some of your existing content into them.
    • Make sure .vscode is not in your .gitignore.
  • Commit the plugin.
  • Follow the setup steps in doc/README.md, then try running the commands. Fix any errors you find.
    • Make sure to double-check the file paths and pattern regex in doc/hexdoc.toml.

Setting up Pages

Follow these steps to set up GitHub Pages: https://hexdoc.hexxy.media/docs/guides/deployment/github-pages

Setting up a PyPI account (optional, but highly recommended)

PyPI is the main Python package repository (like Node's NPM). hexdoc plugins are set up by default to (mostly) automatically publish versions to PyPI when you release a new version of your mod.

  • Create a PyPI account.
  • Follow these steps to configure a pending publisher for your plugin.
    • PyPI Project Name: The name value from your pyproject.toml (ie. hexdoc-yourmodid).
    • Workflow name: build_docs.yml
    • Environment name: pypi
  • Go to your GitHub repo settings > Environments, and create an environment called pypi.
  • Try releasing the plugin to PyPI (push a tag, push a commit starting with [Release], or manually run the hexdoc workflow from the Actions tab).

The default version number for your plugin is 1.0.dev0. You can update this version by editing doc/src/hexdoc_yourmodid/__version__.py.

Next steps

  • Read through the files added by the template - make sure you know what you just added to your repo!
  • If you use VSCode, consider installing the recommended extensions for auto-formatting, linting, and type checking.
  • When you're confident that your book is set up properly and publishing is working, remove .dev0 from your plugin version (doc/src/hexdoc_yourmodid/__version__.py).
  • For more hexdoc examples, take a look at these projects:

FAQ

Why should I publish my plugin to PyPI?