Skip to content

Usage

wj-publish publishes build artifacts. Point it at the build directory and it finds the wheels and the documentation zip to publish.

wj-publish [options] DIR

DIR is the build directory containing the .whl files and the <project>-<version>-docs.zip — usually output/. It is searched for both.

Options

See the CLI Reference for the full, always-up-to-date list of options (generated from wj-publish --help). The most-used ones:

  • -c, --config FILE / -p, --profile NAME — choose the config file and profile
  • --pypi-only / --docs-only — limit what is published
  • -f, --force — overwrite an existing docs version
  • --example-config — print a starter config

By default both PyPI and docs are published, based on what the selected profile configures. If only PyPI is configured (no docs repo), only the wheels are published, and vice versa.

Examples

# Publish everything in output/
wj-publish output/

# Use a specific profile
wj-publish --profile public output/

# Only publish wheels
wj-publish --pypi-only output/

# Re-publish docs for a version that already exists in the repo
wj-publish --docs-only --force output/

# Print a starter config to the default location
wj-publish --example-config > ~/.config/wj-publish/config.json

What gets published

Wheels

Every .whl found is uploaded to the configured PyPI repository (the public PyPI registry by default) with twine, using token authentication.

Documentation

The documentation zip is expected to be named <project>-<version>-docs.zip (the form produced by make build). wj-publish extracts it into <project>/<version>/ inside the docs repository, runs the configured index_command (if any), and pushes. For the WaterJuice docs repo — which builds an index via tools/gen_index.py — the new version becomes available at:

  • https://docs.waterjuice.org/<project>/<version>/
  • https://docs.waterjuice.org/<project>/latest/ (newest stable release, else newest beta)

Publishing a version that already exists fails unless --force is given.

Exit status

wj-publish exits non-zero if any selected step fails. PyPI and docs are independent — a PyPI failure does not skip the docs publish, and the overall exit status reflects whether everything succeeded.