ci_docs.yml

name: validate Docs

on:  # Trigger the workflow on push or pull request
#  push:
#    branches: [main]
  pull_request: {}
  schedule:
    # At the end of every day
    - cron: "0 0 * * *"

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

jobs:
  build-docs:
    runs-on: ubuntu-latest
    env:
      PUB_BRANCH: publication
      PATH_DATASETS: ${{ github.workspace }}/.datasets
    timeout-minutes: 20
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v3
        with:
          fetch-depth: 0  # fetch all history for all branches and tags
      - uses: actions/setup-python@v4
        with:
          python-version: 3.8

      - name: Cache pip
        uses: actions/cache@v3
        with:
          path: ~/.cache/pip
          key: pip-${{ hashFiles('requirements.txt') }}-${{ hashFiles('_requirements/docs.txt') }}
          restore-keys: pip-

      - name: Install dependencies
        run: |
          sudo apt-get update --fix-missing
          sudo apt-get install -y tree
          # install Texlive, see https://linuxconfig.org/how-to-install-latex-on-ubuntu-20-04-focal-fossa-linux
          sudo apt-get install -y cmake pandoc texlive-latex-extra dvipng texlive-pictures
          pip --version
          pip install -q -r requirements.txt -r _requirements/docs.txt
          pip list
        shell: bash

      - name: Process folders
        run: |
          mkdir -p ${PATH_DATASETS}
          head=$(git rev-parse origin/"${{ github.base_ref }}")
          git diff --name-only $head --output=master-diff.txt
          python .actions/assistant.py group-folders master-diff.txt
          printf "Changed folders:\n"
          cat changed-folders.txt
        shell: bash

      - name: ">> output"
        id: changed
        run: python -c "lines = open('changed-folders.txt').readlines(); print(f'::set-output name=nb_dirs::{len(lines)}')"

      - uses: oleksiyrudenko/gha-git-credentials@v2.1
        with:
          token: '${{ secrets.GITHUB_TOKEN }}'
          global: true
      - name: Sync to pub
        run: git merge -s resolve origin/$PUB_BRANCH

      - name: Generate notebooks
        if: steps.changed.outputs.nb_dirs != 0
        run: |
          while IFS= read -r line; do
              python .actions/assistant.py convert-ipynb $line
              python .actions/assistant.py bash-render $line
              cat .actions/_ipynb-render.sh
              bash .actions/_ipynb-render.sh
          done <<< $(cat changed-folders.txt)
        env:
          DRY_RUN: 1
        shell: bash

      - name: Copy notebooks
        if: steps.changed.outputs.nb_dirs != 0
        run: |
          while IFS= read -r line; do
              dir=$(dirname $line)
              mkdir -p changed-notebooks/${dir}
              cp .notebooks/${line}.ipynb changed-notebooks/${dir}/
          done <<< $(cat changed-folders.txt)
          tree changed-notebooks
        shell: bash

      - uses: actions/upload-artifact@v3
        if: steps.changed.outputs.nb_dirs != 0
        with:
          name: notebooks-${{ github.sha }}
          path: changed-notebooks/

      - name: Make Documentation
        working-directory: ./_docs
        run: make html --debug SPHINXOPTS="-W --keep-going"

      - name: Check External Links (Optional)
        working-directory: ./_docs
        run: make --jobs $(nproc) linkcheck
        # ToDO: comment on PR if any link failed
        continue-on-error: true

      - name: Upload built docs
        uses: actions/upload-artifact@v3
        with:
          name: docs-html-${{ github.sha }}
          path: _docs/build/html/
        # Use always() to always run this step to publish test results when there are test failures
        if: success()