Skip to content

wj-publish

A small tool for publishing WaterJuice projects: it uploads platform wheels to PyPI and pushes the built documentation into the git repository that Cloudflare Pages serves.

It is the publish step that runs after a project has been built — the equivalent of make publish.

What it does

  • PyPI — uploads .whl files 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 built 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 publishes the result.

Why?

WaterJuice projects are distributed as Python wheels and documented with MkDocs. Once built, each release needs to land in two places: PyPI and the docs site. wj-publish does both from a single command:

wj-publish output/

where output/ is the build directory containing the .whl files and the <project>-<version>-docs.zip.

Quick start

# Publish everything in output/ (wheels + docs)
wj-publish output/

# Only the wheels, or only the docs
wj-publish --pypi-only output/
wj-publish --docs-only output/

# Overwrite an already-published docs version
wj-publish --force output/

See the Usage and Configuration pages for details.

How it works

wj-publish reads a profile from a JSON config file (~/.config/wj-publish/config.json by default). A profile supplies a PyPI token and the docs git repository URL. Any value can be overridden by a WJ_PUBLISH_* environment variable, so CI can supply secrets without a file on disk.

The documentation site is a static git repository: each project has a directory of versioned subdirectories (serverpeek/1.2.3/, …), and an index.html plus a _redirects file route /<project>/latest/ to the newest version. wj-publish treats its clone of that repository as a disposable cache — cloning on first use, and otherwise fetching and hard-resetting to the remote before adding the new version and pushing.

wj-publish is a pure-Python tool (pip install wj-publish / uvx wj-publish), requiring Python 3.12+. twine is a bundled dependency; git is the one external tool needed at runtime (for the docs push). If a docs.index_command is configured, it is run in the cloned repo after the files are placed (the WaterJuice docs repo uses its own tools/gen_index.py).