Configuration

wj-publish is configured by a JSON file containing one or more named profiles. The format mirrors cal-publish-python, trimmed to the one PyPI upload method and the one docs method (pushing to a git repository, e.g. the WaterJuice docs repo served by Cloudflare Pages).

Config file

Default location: ~/.config/wj-publish/config.json. Override with --config FILE or $WJ_PUBLISH_CONFIG. Generate a starter file with:

wj-publish --example-config > ~/.config/wj-publish/config.json

{
  "profiles": {
    "waterjuice": {
      "pypi": {
        "token": "pypi-AgEI..."
      },
      "docs": {
        "mode": "git",
        "repo": "git@github.com:WaterJuice/docs.git",
        "index_command": "python3 tools/gen_index.py"
      }
    }
  }
}

`pypi`

Key	Default	Description
`token`	—	PyPI API token (or password)
`username`	`__token__`	Upload username
`repository_url`	`https://upload.pypi.org/legacy/`	Upload endpoint

Publishing to a different registry

To publish somewhere other than the public PyPI — TestPyPI, a private index, a GitLab project's PyPI registry, Artifactory, etc. — set repository_url (and username, if the registry expects something other than __token__). It is passed straight through to twine.

"pypi": {
  "token": "...",
  "username": "__token__",
  "repository_url": "https://test.pypi.org/legacy/"
}

A common pattern is one profile per registry (e.g. a waterjuice profile for PyPI and a testpypi profile for test uploads); select with --profile.

`docs`

Key	Default	Description
`mode`	`git`	Publishing method (currently only `git`)
`repo`	—	git URL of the docs repository
`branch`	`main`	Branch to push to
`work_dir`	(under the user cache dir)	Override for the cached clone location
`index_command`	(none)	Command run in the repo after placing files; if unset, the docs are pushed as-is

git mode pushes the docs into a git repository. If the repo has its own tooling to build an index/landing page, point index_command at it (the WaterJuice docs repo uses python3 tools/gen_index.py); leave it unset to just push the files. The mode is recorded explicitly so other publishing methods can be added later without changing the config format.

Selecting a profile

When a config file is used, a profile must be selected (in priority order):

-p, --profile NAME
$WJ_PUBLISH_PROFILE
profile = "NAME" under [tool.wj-publish] in ./pyproject.toml

# pyproject.toml
[tool.wj-publish]
profile = "waterjuice"

Environment variables

Every value can be overridden by an environment variable (these also work with no config file at all, which is convenient in CI):

Variable	Overrides
`WJ_PUBLISH_CONFIG`	config file path
`WJ_PUBLISH_PROFILE`	profile name
`WJ_PUBLISH_PYPI_TOKEN`	`pypi.token`
`WJ_PUBLISH_PYPI_USERNAME`	`pypi.username`
`WJ_PUBLISH_PYPI_REPOSITORY_URL`	`pypi.repository_url`
`WJ_PUBLISH_DOCS_MODE`	`docs.mode`
`WJ_PUBLISH_DOCS_REPO`	`docs.repo`
`WJ_PUBLISH_DOCS_BRANCH`	`docs.branch`
`WJ_PUBLISH_DOCS_WORK_DIR`	`docs.work_dir`
`WJ_PUBLISH_DOCS_INDEX_COMMAND`	`docs.index_command`

Git authentication

The docs push uses whatever credentials the configured repo URL implies. An SSH URL (git@github.com:WaterJuice/docs.git) uses the caller's SSH key / agent — in CI, configure an SSH deploy key with write access to the docs repository.

Runtime dependencies

Python 3.12+ — wj-publish is a pure-Python tool.
twine — a bundled dependency, used for the PyPI upload.
git — an external tool, used to clone, commit, and push the docs repository.
The docs.index_command, if set, runs the docs repository's own index script (e.g. python3 tools/gen_index.py) to regenerate index.html and _redirects.