docs.yaml

name: Docs

# Build API reference docs with pdoc on every push to main.
# On push: build + deploy to GitHub Pages (gh-pages branch).
# On PR:   build only (smoke test, no deploy).

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: write   # needed to push to gh-pages

jobs:
  build:
    name: Build docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install package and pdoc
        run: |
          pip install -e ".[dev]"
          pip install pdoc

      - name: Build HTML docs
        # pdoc 14+ writes directly to -o dir; --no-show-source keeps output clean
        run: pdoc --output-directory site --no-show-source kb_cloud_client

      - name: Add .nojekyll (required for GitHub Pages)
        run: touch site/.nojekyll

      - name: Upload docs artifact
        uses: actions/upload-artifact@v4
        with:
          name: docs-html
          path: site/
          if-no-files-found: error

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - name: Download docs artifact
        uses: actions/download-artifact@v4
        with:
          name: docs-html
          path: site/

      - name: Deploy to gh-pages branch
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
          # Orphan branch keeps gh-pages history small
          force_orphan: true
          enable_jekyll: false
          commit_message: "docs: ${{ github.event.head_commit.message }}"