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:
  generate-files:
    runs-on: ubuntu-20.04
    # https://docs.github.com/en/actions/creating-actions/creating-a-composite-action
    steps:
      #----------------------------------------------
      #       check-out repo and set-up python
      #----------------------------------------------
      - name: Check out repository
        uses: actions/checkout@v3
        with:
          ref: ${{ github.event.pull_request.head.ref }}
          repository: ${{ github.event.pull_request.head.repo.full_name }}
      - name: Set up python
        id: setup-python
        uses: actions/setup-python@v4
        with:
          python-version: 3.9.10

      #----------------------------------------------
      #  -- save a few section by caching poetry --
      #----------------------------------------------
      - name: Load cached Poetry installation
        uses: actions/cache@v2
        with:
          path: ~/.local  # the path depends on the OS
          key: poetry-0  # increment to reset cache
      #----------------------------------------------
      #  -----  install & configure poetry  -----
      #----------------------------------------------
      - name: Install Poetry
        uses: snok/install-poetry@v1
        with:
          version: '1.7.0'
          virtualenvs-create: true
          virtualenvs-in-project: true
          installer-parallel: true

      #----------------------------------------------
      #       load cached venv if cache exists
      #----------------------------------------------
      - name: Load cached venv
        id: cached-poetry-dependencies
        uses: actions/cache@v2
        with:
          path: .venv
          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}-00
      #----------------------------------------------
      # install dependencies if cache does not exist
      #----------------------------------------------
      - name: Install dependencies
        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
        run: poetry install --no-interaction --no-root
      #----------------------------------------------
      # install your root project, if required
      #----------------------------------------------
      - name: Install library
        run: poetry install --no-interaction

      - name: Generate comparison/level library dialect + dataset tables
        run: |
          source .venv/bin/activate
          mv scripts/generate_dialect_comparison_docs.py generate_dialect_comparison_docs.py
          mv scripts/generate_dataset_docs.py generate_dataset_docs.py
          python generate_dialect_comparison_docs.py
          python generate_dataset_docs.py

      - name: Upload generated docs files
        uses: actions/upload-artifact@v3
        with:
          name: generated_files
          path: docs/includes/generated_files

  build:
    runs-on: ubuntu-latest
    needs: generate-files
    steps:
      - uses: actions/setup-python@v4
        with:
          python-version: 3.9

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

      - uses: actions/download-artifact@v3
        with:
          name: generated_files
          path: docs/includes/generated_files

      - 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: true
          args: --offline site/ --verbose './**/*.html'

      - name: Upload built site
        uses: actions/upload-artifact@v3
        with:
          name: built_site
          path: site

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

  deploy:
    runs-on: ubuntu-latest
    needs: build
    # we only deplot on push to master
    # this job doesn't run if this is triggered by a PR
    if: github.event_name == 'push'
    steps:
      - uses: actions/setup-python@v4
        with:
          python-version: 3.9

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

      - uses: actions/download-artifact@v3
        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