docs workflow (viser-project/viser)

name: docs
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  release:
    types: [created]
  workflow_dispatch:
 
concurrency:
  group: docs-${{ github.ref }}
  cancel-in-progress: true
 
permissions:
  contents: write
 
jobs:
  docs:
    timeout-minutes: 30
    runs-on: latchkey-small
    steps:
      # Check out source.
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # This ensures the entire history is fetched so we can switch branches
 
      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
 
      # Get version from pyproject.toml.
      - name: Get version + subdirectory
        run: |
          VERSION=$(uv run --extra dev --python 3.12 python -c "import viser; print(viser.__version__)")
          echo "VISER_RELEASE_WORKFLOW_VERSION=$VERSION" >> $GITHUB_ENV
          echo "VERSION=$VERSION" >> $GITHUB_ENV
          echo "DOCS_SUBDIR=versions/$VERSION" >> $GITHUB_ENV
 
      # Hack to overwrite version.
      - name: Set version to 'main' for pushes (this will appear in the doc banner)
        run: |
          echo "VISER_VERSION_STR_OVERRIDE=main" >> $GITHUB_ENV
        if: github.event_name == 'push'
 
      # Build documentation.
      - name: Building documentation
        run: |
          uv run --extra dev --extra examples --python 3.12 --with-requirements docs/requirements.txt \
            sphinx-build docs/source docs/build -b dirhtml
 
      # Get version from pyproject.toml.
      - name: Override subdirectory to `main/` for pushes
        run: |
          echo "DOCS_SUBDIR=main" >> $GITHUB_ENV
        if: github.event_name == 'push'
 
      # Deploy to version-dependent subdirectory.
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/build
          destination_dir: ${{ env.DOCS_SUBDIR }}
          keep_files: false # This will only erase the destination subdirectory.
          cname: viser.studio
        if: github.event_name != 'pull_request'
 
      # We'll maintain an index of all versions under viser.studio/versions.
      # This will be useful for dynamically generating lists of possible doc links.
      - name: Update versions index.txt
        run: |
          git checkout .  # Revert change to pyproject.toml from earlier...
          git checkout gh-pages
          git pull
          git config --global user.email "yibrenth@gmail.com"
          git config --global user.name "Brent Yi"
          FILE="versions/index.txt"  # Replace with your file path
          if ! grep -qx "$VERSION" "$FILE"; then
            echo "$VERSION" >> "$FILE"
            git add $FILE
            git commit -m "Update versions.txt with new version $VERSION"
            git push origin gh-pages
          fi
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ env.VERSION }}
        if: github.event_name == 'release'