docs.yml

name: Sphinx Docs

on:
  push:
    branches:
      - main
  pull_request:

permissions:
  contents: write

defaults:
  run:
    shell: bash

jobs:
  get_notebooks:
    name: Get list of notebooks
    runs-on: ubuntu-latest
    steps:
      - name: Checkout mrpro repo
        uses: actions/checkout@v4

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

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

  run_notebook:
    name: Run notebook
    needs: 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_path: ${{ fromJson(needs.get_notebooks.outputs.notebook_paths) }}
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

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

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

      - name: Add nb-myst download badge
        run: |
          notebook=${{ matrix.notebook_path }}
          notebook_name=$(basename $notebook)
          download_badge_md="[![Download notebook](https://img.shields.io/badge/Download-notebook-blue?logo=jupyter)](path:$notebook_name)"
          python_command="import nbformat as nbf\n\
          nb = nbf.read(open('$notebook'), as_version=4)\n\
          # if the 1st cell is md and has colab text => add space after\n\
          if nb['cells'][0]['cell_type'] == 'markdown' and 'colab' in nb['cells'][0]['source'].lower():\n\
              nb['cells'][0]['source'] += ' '\n\
          # if there is no md cell with colab => create empty md cell on top\n\
          else:\n\
              nb['cells'].insert(0, nbf.v4.new_markdown_cell())\n\
          nb['cells'][0]['source'] += '$download_badge_md'\n\
          nbf.write(nb, open('$notebook', 'w'))"

          python -c "exec (\"$python_command\")"

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

      - name: Get artifact names
        id: artifact_names
        run: |
          notebook=${{ matrix.notebook_path }}
          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: 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

      - 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