ci-docs.yml

# Reference:
#   - https://github.com/actions/checkout
#   - https://github.com/awalsh128/cache-apt-pkgs-action
#   - https://github.com/conda-incubator/setup-miniconda

name: ci-docs

on:
  pull_request:

  push:
    branches:
      - "main"
      - "v*x"
      - "!conda-lock-auto-update"
      - "!pre-commit-ci-update-config"
      - "!dependabot/*"
    tags:
      - "v*"

  workflow_dispatch:

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

jobs:
  tests:
    name: "${{ matrix.session }} (${{ matrix.version }})"

    runs-on: ${{ matrix.os }}

    defaults:
      run:
        shell: bash -l {0}

    env:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
      ENV_NAME: "ci-docs"

    strategy:
      fail-fast: false
      matrix:
        os: ["ubuntu-latest"]
        version: ["py312"]
        session: ["doctest", "linkcheck"]

    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: "environment configure"
      env:
        # Maximum cache period (in weeks) before forcing a cache refresh.
        CACHE_WEEKS: 2
      run: |
        echo "CACHE_PERIOD=$(date +%Y).$(expr $(date +%U) / ${CACHE_WEEKS})" >> ${GITHUB_ENV}
        echo "LOCK_FILE=requirements/locks/${{ matrix.version }}-lock-linux-64.txt" >> ${GITHUB_ENV}

    - name: "conda package cache"
      uses: ./.github/workflows/composite/conda-pkg-cache
      with:
        cache_period: ${{ env.CACHE_PERIOD }}
        env_name: ${{ env.ENV_NAME }}

    - name: "conda install"
      uses: conda-incubator/setup-miniconda@d2e6a045a86077fb6cad6f5adf368e9076ddaa8d
      with:
        miniforge-version: latest
        activate-environment: ${{ env.ENV_NAME }}
        use-only-tar-bz2: false

    - name: "conda environment cache"
      uses: ./.github/workflows/composite/conda-env-cache
      with:
        cache_period: ${{ env.CACHE_PERIOD }}
        env_name: ${{ env.ENV_NAME }}
        install_packages: "cartopy pip 'tox<4'"

    - name: "conda info"
      run: |
        conda info
        conda list

    - name: "cartopy cache"
      uses: ./.github/workflows/composite/cartopy-cache
      with:
        cache_period: ${{ env.CACHE_PERIOD }}
        env_name: ${{ env.ENV_NAME }}

    - name: "tox cache"
      uses: ./.github/workflows/composite/tox-cache
      with:
        lock_file: ${{ env.LOCK_FILE }}

    - name: "apt cache"
      uses: awalsh128/cache-apt-pkgs-action@a6c3917cc929dd0345bfb2d3feaf9101823370ad
      with:
        packages: libgl1-mesa-glx xvfb
        version: 1.0

    - name: "geovista cache"
      uses: ./.github/workflows/composite/geovista-cache
      with:
        cache_period: ${{ env.CACHE_PERIOD }}

    - name: "${{ matrix.session }} (${{ matrix.version }})"
      run: |
        tox -e ${{ matrix.version }}-${{ matrix.session }}