feat: better stream handling, docs

Author: snus-kin

.coverage

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/dependabot.yml

@@ -1,89 +1,93 @@
-name: Documentation
+name: Build and Deploy Documentation
+
 on:
   push:
-    branches:
-      - main
+    branches: [main, master]
     paths:
       - "docs/**"
       - "src/**"
+      - "examples/**"
+      - "README.md"
       - "pyproject.toml"
       - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [main, master]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "examples/**"
+      - "README.md"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: "Reason for manual documentation build"
+        required: false
+        default: "Manual trigger"
 
-# Sets permissions of the GITHUB_TOKEN
 permissions:
-  contents: write
-  pull-requests: write
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
 
 jobs:
-  build-docs:
+  build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Install uv
         uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
 
-      - name: Install dependencies
-        run: |
-          uv sync --dev --groups docs
+      - name: Set up Python
+        run: uv python install
 
-      - name: Configure Git
-        run: |
-          git config user.name 'github-actions[bot]'
-          git config user.email 'github-actions[bot]@users.noreply.github.com'
+      - name: Install dependencies
+        run: uv sync --locked --group docs
 
       - name: Build documentation
         run: |
           cd docs
-          make clean
-          make html
+          uv run make clean
+          uv run make html
 
-      - name: Prepare docs branch
-        run: |
-          # Create/switch to docs branch
-          git checkout -B docs
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
 
-          # Remove existing docs if any
-          rm -rf docs/build || true
-
-          # Move built docs to root docs/build directory
-          mkdir -p docs/build
-          cp -r docs/_build/html/* docs/build/
-
-          # Stage changes
-          git add docs/build
-
-          # Only proceed if there are changes to commit
-          if git diff --staged --quiet; then
-            echo "No changes to documentation"
-            exit 0
-          fi
-
-          # Commit changes
-          git commit -m "Update documentation from main branch"
-
-          # Push to docs branch
-          git push origin docs --force
-
-      - name: Create Pull Request
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          # Check if PR already exists
-          PR_EXISTS=$(gh pr list --head docs --base main --json number -q length)
-
-          if [ "$PR_EXISTS" -eq "0" ]; then
-            # Create PR if it doesn't exist
-            gh pr create \
-              --base main \
-              --head docs \
-              --title "Documentation Update" \
-              --body "Automated documentation update from main branch.
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
+        with:
+          path: docs/_build/html
 
-              This PR was automatically generated by the documentation workflow when changes were detected in the docs, source code, or project configuration." \
-              --label "documentation"
-          else
-            echo "PR from docs branch already exists. Skipping PR creation."
-          fi
+      - name: Upload build artifacts for debugging
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: docs-build-artifacts
+          path: |
+            docs/_build/
+            docs/*.log
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4