Switch from click to typer and apply template for auto-generating cli reference

.github/actions/setup-python-env/action.yaml

@@ -17,7 +17,7 @@ runs:
         python-version: ${{ inputs.python-version }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v7
+      uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
       with:
         version: ${{ inputs.uv-version }}
         enable-cache: 'true'

.github/workflows/docs.yaml

@@ -0,0 +1,43 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: pages
+  cancel-in-progress: false
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+      - run: uv sync --frozen
+      - run: uv run python scripts/gen_cli_reference.py
+      - run: uv run zensical build --clean -f site-docs/zensical.toml
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site-docs/site
+
+  deploy:
+    needs: build
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v6
+      - uses: actions/deploy-pages@v5
+        id: deployment

.gitignore

@@ -167,6 +167,7 @@ venv.bak/
 
 # mkdocs documentation
 /site
+/site-docs/site
 
 # mypy
 .mypy_cache/

AGENTS.md

@@ -4,17 +4,14 @@
 
 ## Project
 
-
 - **Type**: CLI (Typer)
 
 - **Language**: Python 3.10+
 - **Package manager**: [uv](https://docs.astral.sh/uv/)
 
 ## Entry Points
 
-
-- `deploy/cli.py` — CLI entry point
-
+- `trobz_deploy/cli.py` — CLI entry point
 
 ## Commands
 

Makefile

@@ -51,14 +51,17 @@ help:
 
 .DEFAULT_GOAL := help
 
-
+.PHONY: cli-docs
+cli-docs: ## Regenerate site-docs/docs/cli-reference.md from Typer --help
+	@echo "🚀 Regenerating CLI reference from --help"
+	@uv run python scripts/gen_cli_reference.py
 
 .PHONY: docs
-docs: ## Build the documentation site
+docs: cli-docs ## Build the documentation site (regenerates CLI reference first)
 	@echo "🚀 Building documentation site"
-	@uv run zensical build
+	@uv run zensical build -f site-docs/zensical.toml
 
 .PHONY: docs-serve
-docs-serve: ## Serve the documentation site locally
+docs-serve: cli-docs ## Serve the documentation site locally
 	@echo "🚀 Serving documentation site"
-	@uv run zensical serve
+	@uv run zensical serve -f site-docs/zensical.toml

pyproject.toml

@@ -9,15 +9,15 @@ license = "AGPL-3.0"
 license-files = ["LICENSE"]
 
 dependencies = [
-    "click>=8.0",
+    "typer>=0.20",
     "jinja2>=3.0",
     "pyyaml>=6.0",
 ]
 
 [project.urls]
 Repository = "https://github.com/trobz/deploy.py"
 [project.scripts]
-deploy = "trobz_deploy.cli:cli"
+deploy = "trobz_deploy.cli:app"
 
 [dependency-groups]
 dev = [

scripts/gen_cli_reference.py

@@ -0,0 +1,53 @@
+"""Regenerate site-docs/docs/cli-reference.md from the Typer app.
+
+Invoked by `make cli-docs` (and transitively `make docs`). Keeps the public
+docs site in sync with whatever flags/commands exist in trobz_deploy.main
+without manual edits — add a flag, run `make docs`, commit the diff.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+OUT = Path(__file__).resolve().parent.parent / "site-docs" / "docs" / "cli-reference.md"
+
+HEADER = """---
+icon: lucide/book
+description: Complete reference for every trobz-deploy command, auto-generated from --help.
+tags:
+  - reference
+  - cli
+---
+
+!!! info "Auto-generated"
+    This page is regenerated from `deploy --help` by `make cli-docs`.
+    Do not edit by hand — your changes will be overwritten on the next build.
+
+"""
+
+
+def main() -> None:
+    # `uv` is on PATH in the dev (`make`) and CI (`setup-uv`) environments.
+    body = subprocess.check_output(
+        ["uv", "run", "typer", "trobz_deploy.cli", "utils", "docs", "--name", "deploy"],  # noqa: S607
+        text=True,
+    )
+    # Typer emits `[default: X]`, `[required]`, etc. which Zensical/Markdown
+    # parses as link references. Escape the brackets so they render literally.
+    body = re.sub(
+        r"\[(default|env var|required)([^\]]*)\]",
+        lambda m: rf"\[{m.group(1)}{m.group(2)}\]",
+        body,
+    )
+    OUT.write_text(HEADER + body)
+    try:
+        rel = OUT.relative_to(Path.cwd())
+    except ValueError:
+        rel = OUT
+    print(f"Wrote {rel} ({len(body.splitlines())} lines from typer)")
+
+
+if __name__ == "__main__":
+    main()

site-docs/docs/cli-reference.md

@@ -0,0 +1,107 @@
+---
+icon: lucide/book
+description: Complete reference for every trobz-deploy command, auto-generated from --help.
+tags:
+  - reference
+  - cli
+---
+
+!!! info "Auto-generated"
+    This page is regenerated from `deploy --help` by `make cli-docs`.
+    Do not edit by hand — your changes will be overwritten on the next build.
+
+# `deploy`
+
+Deploy and manage applications on remote servers over SSH.
+
+**Usage**:
+
+```console
+$ deploy [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--config FILE`: Path to the configuration file.  \[default: deploy.yml\]
+* `--verbose`: Print each remote command and its output as it runs.
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `configure`: Configure a new deployment instance.
+* `update`: Update an existing deployment instance.
+* `status`: Show status of a deployment instance.
+
+## `deploy configure`
+
+Configure a new deployment instance.
+
+**Usage**:
+
+```console
+$ deploy configure [OPTIONS] INSTANCE_NAME [SSH_HOST] [REPO_URL]
+```
+
+**Arguments**:
+
+* `INSTANCE_NAME`: \[required\]
+* `[SSH_HOST]`
+* `[REPO_URL]`
+
+**Options**:
+
+* `--type [odoo|python|service]`: Deployment type (auto-detected from instance name prefix if omitted).
+* `-p, --port INTEGER`: SSH port on the remote host.
+* `--force`: Re-run setup steps even if the instance directory already exists.
+* `--repo-subdir TEXT`: Subdirectory within the repo to use as the service root (for monorepos).
+* `--repo-branch TEXT`: Git branch to clone and track (defaults to the repository's default branch).
+* `--help`: Show this message and exit.
+
+## `deploy update`
+
+Update an existing deployment instance.
+
+**Usage**:
+
+```console
+$ deploy update [OPTIONS] INSTANCE_NAME [SSH_HOST]
+```
+
+**Arguments**:
+
+* `INSTANCE_NAME`: \[required\]
+* `[SSH_HOST]`
+
+**Options**:
+
+* `--type [odoo|python|service]`: Deployment type (auto-detected from instance name prefix if omitted).
+* `--db TEXT`: Override the target database name (Odoo only). Can be comma-separated for multiple databases.
+* `-p, --port INTEGER`: SSH port on the remote host.
+* `--ignore-hooks`: Skip all hook execution.
+* `--repo-subdir TEXT`: Subdirectory within the repo to use as the service root (for monorepos).
+* `--repo-branch TEXT`: Git branch to pull (defaults to the currently checked-out branch).
+* `--watch`: Stream service logs with journalctl after a successful update.
+* `--help`: Show this message and exit.
+
+## `deploy status`
+
+Show status of a deployment instance.
+
+**Usage**:
+
+```console
+$ deploy status [OPTIONS] INSTANCE_NAME [SSH_HOST]
+```
+
+**Arguments**:
+
+* `INSTANCE_NAME`: \[required\]
+* `[SSH_HOST]`
+
+**Options**:
+
+* `-p, --port INTEGER`: SSH port on the remote host.
+* `--watch`: Stream service logs with journalctl after showing status.
+* `--help`: Show this message and exit.