Metadata-Version: 2.4
Name: wj-publish
Version: 1.0.0b1
Summary: Publish WaterJuice projects: wheels to PyPI and docs to the Cloudflare Pages git repo
Project-URL: Repository, https://github.com/waterjuice/wj-publish
Project-URL: Documentation, https://docs.waterjuice.org/wj-publish/
Author: WaterJuice
License-Expression: Unlicense
License-File: LICENSE
Keywords: cli,cloudflare-pages,docs,publish,pypi,waterjuice
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Requires-Dist: twine>=6.0.0
Description-Content-Type: text/markdown

# 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

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

## Usage

```bash
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.

```bash
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** — keeps its own cached clone of the docs repository, drops the docs into
  `<project>/<version>/`, regenerates the site index with the repo's 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`):

```json
{
  "profiles": {
    "waterjuice": {
      "pypi": {
        "token": "pypi-AgEI..."
      },
      "docs": {
        "mode": "cloudflare-pages",
        "repo": "git@github.com:WaterJuice/docs.git"
      }
    }
  }
}
```

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`](config.example.json) and the
[Configuration docs](docs/mkdocs/configuration.md) for the full reference.

## Build

```bash
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](https://unlicense.org/) — public domain.
