# plesty docs

Build, preview, and deploy the Sphinx documentation for a Plesty project.

## Subcommands

- `plesty docs serve` — local preview with live reload
- `plesty docs deploy` — publish to a remote pages branch

---

## serve

```bash
plesty docs serve [--dev-addr IP:PORT]
```

Starts a local web server that renders the project documentation and automatically reloads
whenever a `.md` or `.rst` file changes. Useful during active documentation writing.

### Options

| Option | Default | Description |
|---|---|---|
| `--dev-addr` | `127.0.0.1:8000` | Host and port for the preview server |

### Example

```bash
# Default address
plesty docs serve

# Listen on all interfaces at a custom port
plesty docs serve --dev-addr 0.0.0.0:9000
```

Press **Ctrl+C** to stop the server.

---

## deploy

```bash
plesty docs deploy REMOTE_URL TARGET_BRANCH (--release | --latest)
```

Builds the Sphinx documentation and pushes it to `TARGET_BRANCH` on the repository at
`REMOTE_URL`, suitable for GitLab Pages. The branch is created as an orphan if it does not
yet exist.

`--release` and `--latest` are mutually exclusive and one is required:

| Flag | Behaviour |
|---|---|
| `--latest` | Publishes to `html/latest/` — for commits to the default branch |
| `--release` | Publishes to `html/releases/<major>.<minor>/` — for tagged releases |

### Example

```bash
# Deploy development snapshot (latest)
plesty docs deploy \
  https://gitlab-ci-token:${CI_BOT_TOKEN}@gitlab.com/plesty/my-device.git \
  docs-build \
  --latest

# Deploy a versioned release
plesty docs deploy \
  https://gitlab-ci-token:${CI_BOT_TOKEN}@gitlab.com/plesty/my-device.git \
  docs-build \
  --release
```

In practice this command is called by the `deploy-docs` CI component and does not need to
be run manually.