docs.yml

name: docs

on:
  push:
    branches:
      - main
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
    build_docs:
        name: Build docs
        runs-on: ubuntu-latest
        steps:
            - name: Avoid git conflicts when tag and branch pushed at same time
              if: github.ref_type == 'tag'
              run: sleep 60

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

            - name: Install ffmpeg
              uses: FedericoCarboni/setup-ffmpeg@v3
                  
            - name: Install opencv
              run: python -m pip install opencv-python-headless ipywidgets "numpy<2.0"

            - name: Checkout code
              uses: actions/checkout@v4

            - name: Install optimap
              run: python -m pip install .[docs]
              
            - name: Cache excample file downloads
              uses: actions/cache@v4
              with:
                path: |
                    docs/tutorials/optimap_example_data
                key: optimap-example-files

            - name: Cache jupyter notebook cache
              uses: actions/cache@v4
              with:
                path: |
                    docs/.jupyter_cache
                key: docs-jupyter-cache

            - name: Build docs
              run: |
                jcache notebook -p docs/.jupyter_cache list
                python -m sphinx -b dirhtml --doctree-dir docs/doctrees docs docs/_build
                find docs/_build -iname '.jupyter_cache' # should be empty but sometimes it's not
                find docs/_build -iname '.jupyter_cache' -exec rm -rf {} \;
              env:
                TQDM_MININTERVAL: 20

            - name: Sanitize ref name for docs version
              run: echo "DOCS_VERSION=${GITHUB_REF_NAME//[^A-Za-z0-9._-]/_}" >> $GITHUB_ENV

            - name: Move to versioned directory
              run: mv docs/_build .github/pages/$DOCS_VERSION

            - name: Upload artifact
              uses: actions/upload-pages-artifact@v3
              with:
                path: .github/pages

    deploy:
        environment:
            name: github-pages
            url: ${{ steps.deployment.outputs.page_url }}
        runs-on: ubuntu-latest
        needs: build_docs
        steps:
            - name: Deploy to GitHub Pages
              id: deployment
              uses: actions/deploy-pages@v4