documentation.yml

name: docswithmkdoc

on:
  push:
    branches:
      - master

  pull_request:
    branches:
      - master
    paths:
      # files that affect the docs build:
      - docs/**
      - CONTRIBUTING.md
      - mkdocs.yml

  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@v4
        with:
          python-version: 3.9
      - uses: actions/checkout@v3
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
      - name: Cache pip dependencies
        uses: actions/cache@v3
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('scripts/docs-requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      - run: tree docs/

      - name: Install docs dependencies
        run: |
          pip install --upgrade pip
          pip install -r scripts/docs-requirements.txt

      - name: Build documentation
        run: mkdocs build

      - name: Check links
        uses: lycheeverse/lychee-action@v1.8.0
        with:
          fail: false
          args: --offline site/ --verbose './**/*.html'

      - name: Upload built site
        uses: actions/upload-artifact@v4.4.0
        with:
          name: built_site
          path: site

      # some environment info
      - run: pip freeze
      - run: mkdocs --version

  deploy:
    runs-on: ubuntu-latest
    needs: build
    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
    steps:
      - uses: actions/setup-python@v4
        with:
          python-version: 3.9

      - uses: actions/checkout@v3
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - uses: actions/download-artifact@v4.1.7
        with:
          name: built_site
          path: site

      - name: commit and force-push to gh-pages branch
        run: |
          pip install ghp-import==2.1.0
          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git config --global user.name "github-actions[bot]"
          ghp-import -opfm "Update docs from commit ${{ github.sha }}" site