tzst/.github/workflows/publish_docs.yml

name: Publish Documentation

on:
  push:
    branches:
      - main
    paths-ignore:
      - "*.md"
      - "LICENSE"
      - ".gitignore"
  pull_request:
    branches:
      - main
    paths-ignore:
      - "*.md"
      - "LICENSE"
      - ".gitignore"

jobs:
  build-and-deploy-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pages: write
      id-token: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v5
        with:
          fetch-depth: 0

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

      - name: Cache pip dependencies
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-docs-${{ hashFiles('docs/requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-docs-
            ${{ runner.os }}-pip-

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e .
          pip install -r docs/requirements.txt

      - name: Build Sphinx documentation
        run: |
          cd docs
          python -m sphinx -b html . _build -W --keep-going

      - name: Upload documentation artifacts
        uses: actions/upload-artifact@v4
        with:
          name: documentation
          path: docs/_build/
          retention-days: 30

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/_build
          force_orphan: true
          user_name: "github-actions[bot]"
          user_email: "github-actions[bot]@users.noreply.github.com"
          commit_message: "Deploy documentation from ${{ github.sha }}"
          cname: tzst.xi-xu.me

  docs-quality-check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

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

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e .
          pip install -r docs/requirements.txt

      - name: Check documentation links
        run: |
          cd docs
          sphinx-build -b linkcheck . _build/linkcheck -W --keep-going
        continue-on-error: true

      - name: Check documentation coverage
        run: |
          cd docs
          sphinx-build -b coverage . _build/coverage
          if [ -f _build/coverage/python.txt ]; then
            echo "Documentation coverage report:"
            cat _build/coverage/python.txt
          fi
        continue-on-error: true