ci: add pdoc3 docs workflow and simplify release-drafter

.github/workflows/docs-generate.yml

@@ -0,0 +1,73 @@
+name: Generate Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request: {}
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Build documentation
+        run: uv run poe docs-generate
+
+      - name: Get generated docs directory
+        id: docs-dir
+        run: echo "path=$(uv run poe -q get-generated-docs-dir)" >> $GITHUB_OUTPUT
+
+      - name: Upload docs artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-${{ github.run_id }}
+          path: ${{ steps.docs-dir.outputs.path }}
+
+      - name: Setup Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ${{ steps.docs-dir.outputs.path }}
+
+  deploy:
+    name: Publish Docs
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release-drafter.yml

@@ -1,6 +1,7 @@
 name: Release Drafter
 
 on:
+  workflow_dispatch: {}
   push:
     branches:
       - main
@@ -10,86 +11,47 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  update_release_draft:
-    # Only runs on push to main - creates/updates draft release notes
+  draft_release:
+    name: Draft Release
     permissions:
       contents: write
       pull-requests: write
     runs-on: ubuntu-latest
     steps:
-      - uses: aaronsteers/semantic-pr-release-drafter@v0.3.0
+      - name: Create or update draft release
+        uses: aaronsteers/semantic-pr-release-drafter@v0.3.1
         id: release-drafter
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-    outputs:
-      upload_url: ${{ steps.release-drafter.outputs.upload_url }}
-      tag_name: ${{ steps.release-drafter.outputs.tag_name }}
-      release_id: ${{ steps.release-drafter.outputs.id }}
-
-  # Build and upload assets to the draft release (only on push to main)
-  upload_release_assets:
-    name: Upload Release Assets
-    needs: [update_release_draft]
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout Repo
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
       - name: Delete existing release assets
         uses: andreaswilli/delete-release-assets-action@v4.0.0
-        # Delete all existing assets to ensure clean replacement
-        # This prevents stale artifacts from accumulating, e.g. if artifact names change
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          tag: ${{ needs.update_release_draft.outputs.tag_name }}
+          tag: ${{ steps.release-drafter.outputs.tag_name }}
           deleteOnlyFromDrafts: true
 
+      - name: Checkout Repo
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
           version: "latest"
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Get version from draft release tag
-        id: version
-        run: |
-          TAG_NAME="${{ needs.update_release_draft.outputs.tag_name }}"
-          # Remove 'v' prefix if present
-          VERSION="${TAG_NAME#v}"
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          echo "Building version: $VERSION"
-
       - name: Build package
+        run: UV_DYNAMIC_VERSIONING_BYPASS="${TAG_NAME#v}" uv build
         env:
-          UV_DYNAMIC_VERSIONING_BYPASS: ${{ steps.version.outputs.version }}
-        run: uv build
-
-      - name: Upload wheel to draft release
-        uses: svenstaro/upload-release-action@v2
-        with:
-          repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: dist/*.whl
-          release_id: ${{ needs.update_release_draft.outputs.release_id }}
-          overwrite: true
-          file_glob: true
-          draft: true
+          TAG_NAME: ${{ steps.release-drafter.outputs.tag_name }}
 
-      - name: Upload sdist to draft release
+      - name: Upload assets to draft release
         uses: svenstaro/upload-release-action@v2
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: dist/*.tar.gz
-          release_id: ${{ needs.update_release_draft.outputs.release_id }}
+          file: dist/*
+          release_id: ${{ steps.release-drafter.outputs.id }}
           overwrite: true
           file_glob: true
           draft: true

poe_tasks.toml

@@ -24,9 +24,10 @@ install = "uv sync --extra dev"
 install-prod = "uv sync"
 build = "uv build"
 
-# Documentation (placeholder for future)
-docs = "echo 'Documentation generation not yet configured'"
-docs-serve = "echo 'Documentation serving not yet configured'"
+# Documentation with pdoc3
+docs-generate = "pdoc --html --output-dir docs/generated fastmcp_extensions --force"
+docs-preview = { shell = "pdoc --html --output-dir docs/generated fastmcp_extensions --force && open docs/generated/fastmcp_extensions/index.html" }
+get-generated-docs-dir = "echo docs/generated/fastmcp_extensions"
 
 # Development helpers
 clean = "rm -rf .pytest_cache .coverage htmlcov dist .ruff_cache"

pyproject.toml

@@ -97,3 +97,9 @@ ignore = ["DEP004"]  # Ignore misplaced dev dependencies (common for test framew
 [tool.deptry.per_rule_ignores]
 # uvicorn is a transitive dependency through fastmcp, used for HTTP server testing
 DEP003 = ["uvicorn"]
+
+[dependency-groups]
+dev = [
+    "pdoc3>=0.11.6",
+    "poethepoet>=0.37.0",
+]