name: CI Docs

on:
  push:
    branches:
    - main
  pull_request:
    branches:
    - main

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


env:
  LIBROSA_DOC_DEBUG: True  # Disable docstring example execution

jobs:
    setup:
        name: "Doc environment setup"
        runs-on: ${{ matrix.os }}
        strategy:
            fail-fast: true
            matrix:
                include:
                    - os: ubuntu-latest
                      python-version: "3.8"
                      channel-priority: "flexible"
                      envfile: ".github/environment-docs.yml"
        steps:
        - uses: actions/checkout@v4
          with:
            fetch-depth: 0

        - name: Cache conda
          uses: actions/cache@v4
          env:
            # Increase this value to reset cache if etc/example-environment.yml has not changed
            CACHE_NUMBER: 0
          with:
            path: ~/conda_pkgs_dir
            key: ${{ runner.os }}-${{ matrix.python-version }}-conda-${{ env.CACHE_NUMBER }}-${{ hashFiles( matrix.envfile ) }}

        - name: Install Conda environment
          uses: conda-incubator/setup-miniconda@v3
          with:
            auto-update-conda: false
            python-version: ${{ matrix.python-version }}
            add-pip-as-python-dependency: true
            auto-activate-base: false
            activate-environment: docs
            channel-priority: ${{ matrix.channel-priority }}
            environment-file: ${{ matrix.envfile }}
            use-only-tar-bz2: false # IMPORTANT: This needs to be set for caching to work properly!

        - name: Conda info
          shell: bash -l {0}
          run: |
            conda info -a
            conda list

        - name: Install librosa
          shell: bash -l {0}
          run: python -m pip install --upgrade-strategy only-if-needed -e .[docs]

        - name: Build multi-version site
          shell: bash -l {0}
          run: |
            sphinx-multiversion -D smv_latest_version=$(./scripts/get_latest_release.sh) docs build/html
            touch build/html/.nojekyll
            cp docs/docsite-index-redirect.html build/html/index.html
            ln -srf build/html/$(./scripts/get_latest_release.sh) build/html/latest  # auto-link the latest tag

        - name: Link checking
          id: linkcheck
          shell: bash -l {0}
          working-directory: docs
          run: make linkcheck

        - name: Check for broken links
          shell: bash -l {0}
          run: |
            if [[ -n "$(find build/html/ -type l ! -exec test -e {} \; -print -quit)" ]]; then false; fi
