wj-publish 1.0.0b3

Publish WaterJuice projects: wheels to PyPI and docs to the Cloudflare Pages git repo

wj-publish

Publish WaterJuice projects: upload platform wheels to PyPI and push built documentation into the git repository that Cloudflare Pages serves.

wj-publish is the publish step that runs after a project is built — the WaterJuice-specific successor to cal-publish-python, trimmed to the one PyPI upload method and the one docs method actually used. It is a small pure-Python tool.

Install

pip install wj-publish
# or
uvx wj-publish --help

Usage

wj-publish [options] DIR

DIR is the build output directory (usually output/) containing the .whl files and the <project>-<version>-docs.zip. By default both PyPI and docs are published.

wj-publish output/              # publish wheels + docs
wj-publish --pypi-only output/  # wheels only
wj-publish --docs-only output/  # docs only
wj-publish --force output/      # overwrite an existing docs version
wj-publish --example-config     # print a starter config

Option	Description
-c, --config FILE	Config file (default: $WJ_PUBLISH_CONFIG or ~/.config/wj-publish/config.json)
-p, --profile NAME	Profile (default: $WJ_PUBLISH_PROFILE or [tool.wj-publish] in pyproject.toml)
--pypi-only / --docs-only	Limit what is published
-f, --force	Overwrite an existing docs version
-v, --verbose	Verbose output
--example-config	Print an example config file and exit
--version / --help	Info and exit

How it works

• PyPI — uploads each .whl with twine to the configured repository (the public PyPI registry by default), using token authentication.
• Docs — git mode: keeps its own cached clone of the docs repository, drops the docs into <project>/<version>/, optionally runs a configured index_command (the WaterJuice docs repo uses its own tools/gen_index.py), then commits and pushes. Cloudflare Pages serves the result at https://docs.waterjuice.org/<project>/.

External tool needed at runtime: git (for the docs push). twine is a bundled dependency.

Configuration

A JSON file with named profiles (default ~/.config/wj-publish/config.json):

{
  "profiles": {
    "waterjuice": {
      "pypi": {
        "token": "pypi-AgEI..."
      },
      "docs": {
        "mode": "git",
        "repo": "[e-mail]:WaterJuice/docs.git",
        "index_command": "python3 tools/gen_index.py"
      }
    }
  }
}

Generate a starter file with wj-publish --example-config. Every value can be overridden by a WJ_PUBLISH_* environment variable (so CI can run with no config file). See config.example.json and the Configuration docs for the full reference.

Build

make build      # build the wheel + docs into output/
make publish    # publish output/ (dogfoods wj-publish)
make check      # ruff lint + format check

Licence

Released under the Unlicense — public domain.