ci.yml

name: CI

on:
  push:
    branches: [ main ]
    paths-ignore: ["web/**", "**.md", "README.rst"]
  pull_request:
    branches: [ main ]
    paths-ignore: ["web/**", "**.md", "README.rst"]

env:
  latest_python: "3.14"
  supported_pythons: '["3.10", "3.11", "3.12", "3.13", "3.14"]'

jobs:
  conf:
    # This job is needed to route the global environment variables into
    # a context that's available for matrix (and name, but that's unimportant)
    name: Prepare Test Plan
    runs-on: ubuntu-latest
    outputs:
      latest_python: ${{ steps.set-vars.outputs.latest_python }}
      supported_pythons: ${{ steps.set-vars.outputs.supported_pythons }}
    steps:
      - name: Report Plan
        id: set-vars
        run: |
          echo "latest_python=$latest_python" >> $GITHUB_OUTPUT
          echo "supported_pythons=$supported_pythons" >> $GITHUB_OUTPUT

  lint:
    name: Lint code (${{ needs.conf.outputs.latest_python }}, ubuntu-latest)
    needs: conf
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash -l {0}
    steps:
      - uses: actions/checkout@v4
      - uses: conda-incubator/setup-miniconda@v3
        with:
          auto-update-conda: true
          python-version: ${{ env.latest_python }}
          environment-file: ci/conda_host_env.yml
      - name: Install dependencies
        run: |
          python -m ensurepip
          pip install -r ci/requirements.lint.txt
          conda list
      - name: Run Ruff
        run: |
          ruff check --output-format=github .

  doc:
    name: Build Documentation (${{ needs.conf.outputs.latest_python }}, ubuntu-latest)
    needs: ["conf", "lint"]
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash -l {0}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # to prevent a "Git clone too shallow" warning by Sphinx
      - uses: conda-incubator/setup-miniconda@v3
        with:
          auto-update-conda: true
          # Pin to 3.13 for now because no Sphinx is compatible with Python 3.14
          python-version: "3.13"
          environment-file: ci/conda_host_env.yml
      - name: Install dependencies
        run: |
          python -m ensurepip
          pip install -r ci/requirements.doc.txt
          pip install .
          conda list
      - name: Make documentation
        run: make doc
      # save built documentation (HTML) for deployment
      - name: Modify documentation
        if: github.event_name == 'push'
        run: |
          python doc/suburl.py
          python doc/metatag.py
          python doc/editmap.py
      - name: Save documentation
        if: github.event_name == 'push'
        uses: actions/upload-artifact@v4
        with:
          name: docpack
          path: doc/build/html/

  # full-scale test with latest Python
  test-latest:
    name: Test (${{ needs.conf.outputs.latest_python }}, ${{ matrix.os }})
    needs: conf
    runs-on: ${{ matrix.os }}
    defaults:
      run:
        shell: bash -l {0}
    strategy:
      fail-fast: true
      # https://docs.github.com/en/actions/using-github-hosted-runners/
      # about-github-hosted-runners/about-github-hosted-runners#standard-
      # github-hosted-runners-for-public-repositories
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest, ubuntu-24.04-arm, macos-15-intel]
    steps:
      - uses: actions/checkout@v4
      - uses: conda-incubator/setup-miniconda@v3
        with:
          auto-update-conda: true
          python-version: ${{ env.latest_python }}
          environment-file: ci/conda_host_env.yml
      - name: Install dependencies
        run: |
          conda install -q --yes -c conda-forge --file ci/conda_requirements.txt --file ci/requirements.test.txt
          python -m ensurepip
          pip install --no-deps .
          conda list
      # install anndata and polars here to test as optional dependencies.
      # encountered errors when installing using conda
      - name: Install optional dependencies
        run: |
          pip install anndata polars
          conda list
      - name: Run unit tests
        env:
          WITH_COVERAGE: "TRUE"
        run: make test

        # upload coverage reports to Codecov (only under ubuntu-latest)
      - name: Generate coverage reports
        if: runner.os == 'Linux' && runner.arch == 'X64'
        run: |
          cd ci && coverage lcov --rcfile ../.coveragerc
      - name: Upload coverage reports to Codecov
        if: runner.os == 'Linux' && runner.arch == 'X64'
        uses: codecov/codecov-action@v4.2.0
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          slug: scikit-bio/scikit-bio

  # test under all combinations of environments (Python versions, operating systems, PyPI vs Conda)
  test-all:
    name: Test (${{ matrix.python_version }}, ${{ matrix.os }}, ${{ fromJSON('["pypi", "conda"]')[matrix.use_conda] }})
    runs-on: ${{ matrix.os }}
    needs: ["conf", "test-latest", "lint"]
    defaults:
      run:
        shell: bash -l {0}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python_version: ${{ fromJSON(needs.conf.outputs.supported_pythons) }}
        use_conda: [true, false]
    steps:
      - uses: actions/checkout@v4
      # set up conda environment
      - name: Setup conda environment
        if: ${{ matrix.use_conda }}
        uses: conda-incubator/setup-miniconda@v3
        with:
          auto-update-conda: true
          python-version: ${{ matrix.python_version }}
          environment-file: ci/conda_host_env.yml
      # set up CPython environment (pip)
      - name: Setup CPython environment
        if: ${{ !matrix.use_conda }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python_version }}
      # conda installation
      - name: Install dependencies (conda)
        if: ${{ matrix.use_conda }}
        run: |
          conda install -q --yes -c conda-forge --file ci/conda_requirements.txt --file ci/requirements.test.txt
          python -m ensurepip
          pip install --no-deps .
          conda list
      # pip installation
      - name: Install dependencies
        if: ${{ !matrix.use_conda }}
        run: |
          python -m ensurepip
          pip install --prefer-binary -r ci/conda_requirements.txt -r ci/requirements.test.txt
          pip install --no-deps .
          pip list
      - name: Run unit tests
        env:
          WITH_COVERAGE: "TRUE"
        run: make test

  # deploy the current development documentation to the website
  # only when event is push and all tests have passed
  deploy-doc:
    name: Deploy documentation
    if: github.event_name == 'push'
    needs: ["doc", "test-all"]
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash -l {0}
    steps:
      # load documentation built by job "doc"
      - name: Load documentation
        uses: actions/download-artifact@v4
        with:
          name: docpack
          path: docpack
      # checkout website repo
      - name: Check out website
        uses: actions/checkout@v4
        with:
          repository: scikit-bio/scikit-bio.github.io
          path: website
          ssh-key: ${{ secrets.SSH_DEPLOY_KEY }}
      # synchronize documentation to website's docs/dev directory
      - name: Update documentation
        run: rsync -av --delete docpack/ website/docs/dev
      # push website back to repo
      - name: Push website
        run: |
          cd website
          git config user.name "${{ github.actor }}"
          git config user.email "${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com"
          git add -A
          git commit -m "Update from ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}"
          git push