docs.yml

name: Build docs

on:
    workflow_call:
    push:
    release:
        types:
            - published

jobs:
    build_docs:
        name: Build docs
        runs-on: ubuntu-latest
        permissions:
          contents: write
        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@v2
              with:
                  python-version: 3.12

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

            - name: Install optimap
              run: pip install .[docs]
            
            - name: Install opencv
              run: pip install opencv-python-headless ipywidgets

            - name: Install ffmpeg
              uses: FedericoCarboni/setup-ffmpeg@v3
              
            - name: Cache file downloads and jupyter notebook execution
              uses: actions/cache@v4
              with:
                path: |
                    docs/tutorials/optimap_example_data
                    docs/_build/.jupyter_cache
                key: docs-example-files

            - name: Build docs
              run: python -m sphinx -b dirhtml docs docs/_build/html

            # - name: Upload artifact
            #   uses: actions/upload-artifact@v4
            #   with:
            #     path: docs/_build/html
            #     name: juypter_cache

            - 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/html .github/pages/$DOCS_VERSION

            - name: Publish Docs to gh-pages
              if: github.ref_type == 'tag' || github.ref_name == 'main'
              # We pin to the SHA, not the tag, for security reasons.
              # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
              uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
              with:
                github_token: ${{ secrets.GITHUB_TOKEN }}
                publish_dir: .github/pages
                keep_files: true