docs.yml

name: Sphinx Docs

on:
  push:
    branches:
      - main
  pull_request:

permissions:
  contents: write

defaults:
  run:
    shell: bash

jobs:
  convert_scripts:
    name: Translate scripts to notebooks
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: write
    outputs:
      commit_hash: ${{ steps.add-commit-push.outputs.commit_hash }}
    container:
      image: ghcr.io/ptb-mr/mrpro_py311:latest
      options: --user runner
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.commit }}
          ref: ${{ github.event.pull_request.head.ref }}
          fetch-depth: 0

      - name: Install mrpro and dependencies
        run: pip install --upgrade --upgrade-strategy "eager" .[notebook]

      - name: Translate scripts to notebooks
        run: |
          scripts=$(ls ./examples/*.py)
          for script in $scripts
            do jupytext --set-kernel "python3" --update --output ${script//.py/.ipynb} $script
          done

      - name: Check if any notebooks have been changed
        uses: tj-actions/verify-changed-files@v20
        id: verify-changed-notebooks
        with:
          files: ./examples/*.ipynb

      - name: Commit notebooks
        if: steps.verify-changed-notebooks.outputs.files_changed == 'true'
        uses: actions4git/add-commit-push@v1
        with:
          commit-message: Notebooks updated

      - name: Get hash of last commit
        id: add-commit-push
        run: echo "commit_hash=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT

  get_notebooks:
    name: Get list of notebooks
    needs: convert_scripts
    runs-on: ubuntu-latest
    steps:
      - name: Checkout mrpro repo
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.convert_scripts.outputs.commit_hash }}

      - id: set-matrix
        run: |
          echo "notebooks=$(find examples -type f -name '*.ipynb' | jq -R -s -c 'split("\n")[:-1]')" >> $GITHUB_OUTPUT

      - name: Notebook overview
        run: |
          echo "jupyter-notebooks: ${{ steps.set-matrix.outputs.notebooks }}"
    outputs:
      notebooks: ${{ steps.set-matrix.outputs.notebooks }}

  run_notebook:
    name: Run notebook
    needs: [convert_scripts, get_notebooks]
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: write
    container:
      image: ghcr.io/ptb-mr/mrpro_py311:latest
      options: --user root
    strategy:
      fail-fast: false
      matrix:
        notebook: ${{ fromJson(needs.get_notebooks.outputs.notebooks) }}
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.convert_scripts.outputs.commit_hash }}

      - name: Install mrpro and dependencies
        run: pip install --upgrade --upgrade-strategy "eager" .[notebook]

      - name: Notebook name
        run: |
          echo "current jupyter-notebook: ${{ matrix.notebook }}"

      - name: Run notebook
        uses: fzimmermann89/run-notebook@v3
        env:
          RUNNER: ${{ toJson(runner) }}
        with:
          notebook: ./${{ matrix.notebook }}

      - name: Get artifact names
        id: artifact_names
        run: |
          notebook=${{ matrix.notebook }}
          echo "ARTIFACT_NAME=$(basename ${notebook/.ipynb})" >> $GITHUB_OUTPUT
          echo "IPYNB_EXECUTED=$(basename $notebook)" >> $GITHUB_OUTPUT

      - name: Upload notebook
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: ${{ steps.artifact_names.outputs.ARTIFACT_NAME }}
          path: ${{ github.workspace }}/nb-runner.out/${{ steps.artifact_names.outputs.IPYNB_EXECUTED }}
        env:
          RUNNER: ${{ toJson(runner) }}

  create_documentation:
    name: Build and deploy documentation
    needs: [convert_scripts, run_notebook]
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/ptb-mr/mrpro_py311:latest
      options: --user runner
    permissions:
      pull-requests: write
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.convert_scripts.outputs.commit_hash }}

      - name: Install mrpro and dependencies
        run: pip install --upgrade --upgrade-strategy "eager" .[docs]

      - name: Download executed notebook ipynb files
        id: download
        uses: actions/download-artifact@v4
        with:
          path: ./docs/source/_notebooks/
          merge-multiple: true

      - name: Build docs
        run: |
          sphinx-build -b html ./docs/source ./docs/build/html
          rm -rf ./docs/build/html/.doctrees

      - name: Save Documentation
        id: save_docu
        uses: actions/upload-artifact@v4
        with:
          name: Documentation
          path: docs/build/html/

      - run: echo 'Artifact url ${{ steps.save_docu.outputs.artifact-url }}'

      - run: echo 'Event number ${{ github.event.number }}'

      - run: echo 'Event name ${{github.event_name}}'

      - name: Update PR with link to summary
        if: github.event_name == 'pull_request'
        uses: edumserrano/find-create-or-update-comment@v3
        with:
          issue-number: ${{ github.event.pull_request.number }}
          body-includes: '<!-- documentation build ${{ github.event.number }} -->'
          comment-author: 'github-actions[bot]'
          body: |
            <!-- documentation build ${{ github.event.number }} -->
            ### :books: Documentation
            :file_folder: [Download as zip](${{ steps.save_docu.outputs.artifact-url }})
            :mag: [View online](https://zimf.de/zipserve/${{ steps.save_docu.outputs.artifact-url }}/)
          edit-mode: replace

      - name: Upload pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/build/html/
        if: github.event_name != 'pull_request'

  deploy:
    if: github.ref == 'refs/heads/main'
    permissions:
        pages: write
        id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: create_documentation
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}

  # Cancel in-progress runs when a new workflow with the same group name is triggered
  cancel-in-progress: true