Refactor CI workflows, improve typing, and enhance documentation

.github/workflows/CI.yml

@@ -4,14 +4,14 @@ on:
   push:
     tags:
       - "v*"
-  workflow_run:
-    workflows: ["Release"]
-    types: [completed]
-  workflow_dispatch:
 
 permissions:
   contents: read
 
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: false
+
 env:
   CARGO_TERM_COLOR: always
 
@@ -31,13 +31,33 @@ jobs:
       - name: Install dev dependencies
         run: uv sync --group dev --no-install-project
       - name: Ruff lint
-        run: uv run --no-project --with ruff==0.11.4 ruff check .
+        run: uv run --no-project ruff check .
       - name: Ruff format check
-        run: uv run --no-project --with ruff==0.11.4 ruff format --check .
+        run: uv run --no-project ruff format --check .
+
+  tests:
+    name: Python Tests
+    needs: quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install dev dependencies
+        run: uv sync --group dev --no-install-project
+      - name: Build native extension
+        run: uv run maturin develop
+      - name: Run pytest
+        run: uv run pytest -q
 
   linux:
     name: Linux manylinux wheels
-    needs: quality
+    needs: [quality, tests]
     runs-on: ${{ matrix.platform.runner }}
     strategy:
       fail-fast: false
@@ -82,7 +102,7 @@ jobs:
 
   android:
     name: Android wheels
-    needs: quality
+    needs: [quality, tests]
     runs-on: ubuntu-22.04
     strategy:
       fail-fast: false
@@ -118,7 +138,7 @@ jobs:
 
   windows:
     name: Windows wheels
-    needs: quality
+    needs: [quality, tests]
     runs-on: ${{ matrix.platform.runner }}
     strategy:
       fail-fast: false
@@ -153,7 +173,7 @@ jobs:
 
   macos:
     name: macOS wheels
-    needs: quality
+    needs: [quality, tests]
     # Both targets use macos-latest (Apple Silicon) — x86_64 is cross-compiled.
     # macos-13 runners have very long queues (12h+); macos-latest is faster.
     runs-on: macos-latest
@@ -185,7 +205,7 @@ jobs:
 
   sdist:
     name: Source distribution
-    needs: quality
+    needs: [quality, tests]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -205,11 +225,7 @@ jobs:
 
   release:
     name: Publish to PyPI
-    if: >
-      ${{
-        startsWith(github.ref, 'refs/tags/v') ||
-        (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')
-      }}
+    if: startsWith(github.ref, 'refs/tags/v')
     needs: [linux, android, windows, macos, sdist]
     runs-on: ubuntu-latest
     permissions:

.github/workflows/docs.yml

@@ -2,14 +2,14 @@ name: Documentation
 
 on:
   push:
-    branches: [master, main]
+    branches: [master, main, dev]
     paths:
       - "docs/**"
       - "mkdocs.yml"
       - "python/tryx/**"
 
   pull_request:
-    branches: [master, main]
+    branches: [master, main, dev]
     paths:
       - "docs/**"
       - "mkdocs.yml"
@@ -21,10 +21,6 @@ on:
         description: "Version to deploy (e.g. 0.7, 0.8)"
         required: false
         type: string
-      delete_version:
-        description: "Version to delete"
-        required: false
-        type: string
 
 permissions:
   contents: write
@@ -51,14 +47,14 @@ jobs:
 
       - uses: astral-sh/setup-uv@v5
 
+      - uses: dtolnay/rust-toolchain@stable
+
       - name: Install dependencies
-        run: |
-          uv sync --group docs --no-install-project
-          uv pip install pyright mypy --system
+        run: uv sync --group dev --group docs --no-install-project
 
       - name: Validate .pyi stubs with pyright
         run: |
-          pyright python/tryx/client.pyi \
+          uv run --no-project pyright python/tryx/client.pyi \
                  python/tryx/events.pyi \
                  python/tryx/types.pyi \
                  python/tryx/wacore.pyi \
@@ -71,7 +67,7 @@ jobs:
 
       - name: Validate .pyi stubs with mypy
         run: |
-          mypy python/tryx/client.pyi \
+          uv run --no-project mypy python/tryx/client.pyi \
                python/tryx/events.pyi \
                python/tryx/types.pyi \
                python/tryx/wacore.pyi \
@@ -84,16 +80,14 @@ jobs:
                --ignore-missing-imports
 
       - name: Build docs (validation only)
-        run: uv run --no-project mkdocs build --strict
-        env:
-          PYTHONPATH: python
+        run: uv run --no-project zensical build -f mkdocs.yml -s
 
-  # ── Job 2: Deploy (runs on push to master or tag) ──────────────────────────
+  # ── Job 2: Deploy (runs on push or manual trigger) ─────────────────────────
   deploy:
     name: Deploy Documentation
     needs: validate
     runs-on: ubuntu-latest
-    if: github.event_name == 'push'
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     steps:
       - uses: actions/checkout@v4
         with:
@@ -107,9 +101,7 @@ jobs:
       - uses: astral-sh/setup-uv@v5
 
       - name: Install dependencies
-        run: |
-          uv sync --group docs --no-install-project
-          uv pip install mike
+        run: uv sync --group dev --group docs --no-install-project
 
       - name: Configure git
         run: |
@@ -124,83 +116,31 @@ jobs:
           echo "Deploying docs for version: $VERSION"
           uv run --no-project mike deploy --push --update-aliases "$VERSION" latest
           uv run --no-project mike set-default --push latest
-        env:
-          PYTHONPATH: python
 
-      # Auto-deploy from master → "latest" (without version number)
-      - name: Deploy latest docs (from master)
-        if: "!startsWith(github.ref, 'refs/tags/')"
+      # Auto-deploy from master → "dev" version
+      - name: Deploy dev docs (from master)
+        if: "!startsWith(github.ref, 'refs/tags/') && github.event_name == 'push'"
         run: |
-          echo "Deploying docs as latest"
+          echo "Deploying docs as dev"
           uv run --no-project mike deploy --push --update-aliases dev latest
           uv run --no-project mike set-default --push latest
-        env:
-          PYTHONPATH: python
-
-      - name: List deployed versions
-        if: success()
-        run: uv run --no-project mike list
 
-  # ── Job 3: Manual deploy (workflow_dispatch) ────────────────────────────────
-  manual_deploy:
-    name: Manual Deploy
-    runs-on: ubuntu-latest
-    if: github.event_name == 'workflow_dispatch'
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          submodules: recursive
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - uses: astral-sh/setup-uv@v5
-
-      - name: Install dependencies
-        run: |
-          uv sync --group docs --no-install-project
-          uv pip install mike
-
-      - name: Configure git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
-      # Deploy custom version
-      - name: Deploy custom version
-        if: inputs.version != ''
+      # Manual deploy with custom version
+      - name: Deploy custom version (manual)
+        if: github.event_name == 'workflow_dispatch' && inputs.version != ''
         run: |
           echo "Deploying docs for version: ${{ inputs.version }}"
           uv run --no-project mike deploy --push --update-aliases "${{ inputs.version }}" latest
           uv run --no-project mike set-default --push latest
-        env:
-          PYTHONPATH: python
 
-      # Delete a version
-      - name: Delete docs version
-        if: inputs.delete_version != ''
+      # Manual deploy without version → deploy as dev
+      - name: Deploy dev docs (manual)
+        if: github.event_name == 'workflow_dispatch' && inputs.version == ''
         run: |
-          echo "Deleting docs version: ${{ inputs.delete_version }}"
-          uv run --no-project mike delete --push "${{ inputs.delete_version }}"
-        env:
-          PYTHONPATH: python
+          echo "Deploying docs as dev"
+          uv run --no-project mike deploy --push --update-aliases dev latest
+          uv run --no-project mike set-default --push latest
 
       - name: List deployed versions
         if: success()
         run: uv run --no-project mike list
-
-  # ── Job 4: Deploy to GitHub Pages (only for tag releases) ──────────────────
-  deploy_pages:
-    name: Deploy to GitHub Pages
-    needs: deploy
-    runs-on: ubuntu-latest
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -31,8 +31,8 @@ jobs:
 
       - uses: dtolnay/rust-toolchain@stable
 
-      - name: Install python-semantic-release
-        run: pip install "python-semantic-release>=9.21.1"
+      - name: Install dependencies
+        run: uv sync --group dev --no-install-project
 
       - name: Python Semantic Release
         id: release

.pre-commit-config.yaml

@@ -15,33 +15,33 @@ repos:
     hooks:
       - id: ruff-check
         name: ruff check
-        entry: uv run ruff check --fix
+        entry: uv run --no-project ruff check --fix
         language: system
         types_or: [python, pyi]
 
       - id: ruff-format
         name: ruff format
-        entry: uv run ruff format
+        entry: uv run --no-project ruff format
         language: system
         types_or: [python, pyi]
 
       - id: pyright
         name: pyright type check
-        entry: uv run pyright
+        entry: uv run --no-project pyright
         language: system
         types: [python]
         pass_filenames: false
         files: "^python/tryx/.*\\.(py|pyi)$"
 
       - id: stub-parity
         name: check stub parity
-        entry: uv run python scripts/check_stub_parity.py
+        entry: uv run --no-project python scripts/check_stub_parity.py
         language: system
         pass_filenames: false
         files: "^python/tryx/.*\\.(py|pyi)$"
 
       - id: conventional-commit-message
         name: conventional commit message
-        entry: uv run python scripts/check_commit_message.py
+        entry: uv run --no-project python scripts/check_commit_message.py
         language: system
         stages: [commit-msg]