documentation.yml

name: documentation
on:
  push:
    branches: [ main, data-fetch-docs-build ]
    paths:
      - sed/**/*
      - docs/**
      - tutorial/**
      - .github/workflows/documentation.yml
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # - name: Maximize build space
      #   uses: easimon/maximize-build-space@master
      #   with:
      #     root-reserve-mb: 2048
      #     swap-size-mb: 1024
      #     remove-dotnet: 'true'
      #     remove-codeql: 'true'
      #     remove-android: 'true'
      #     remove-docker-images: 'true'

      - name: Check out the repository
        uses: actions/checkout@v4
        with:
          lfs: true

      - name: Setup Python, Poetry and Dependencies
        uses: packetcoders/action-setup-cache-python-poetry@main
        with:
          python-version: 3.8
          poetry-version: 1.2.2

      - name: Install notebook dependencies
        run: poetry install -E notebook --with docs

      - name: Install pandoc
        run: |
          sudo wget https://github.com/jgm/pandoc/releases/download/3.1.8/pandoc-3.1.8-1-amd64.deb
          sudo dpkg -i pandoc-3.1.8-1-amd64.deb > /dev/null 2>&1

      - name: Remove SXP notebook
        run: |
          cp -r $GITHUB_WORKSPACE/sed/config $GITHUB_WORKSPACE/docs/sed
          rm $GITHUB_WORKSPACE/tutorial/5_sxp_workflow.ipynb

      - name: Cache build
        uses: actions/cache/restore@v3
        id: restore-cache
        with:
          path: |
             _build/
             docs/tutorial/*ipynb
             docs/tutorial/tutorial_checksums.txt
          key: ${{ runner.os }}-docs-build-${{ hashFiles('docs/tutorial/tutorial_checksums.txt') }}
          restore-keys: |
            ${{ runner.os }}-docs-build-

      - name: Compute notebook checksums
        id: compute-checksums
        run: |
          find tutorial -name "*.ipynb" | sort | xargs sha256sum > tutorial_checksums.txt

      - name: Move cached executed notebooks
        run: python docs/move_changed_notebooks.py

      - name: Download datasets
        run: poetry run python docs/download_datasets.py

      # - name: Build Flash parquet files
      #   run: |
      #     cd $GITHUB_WORKSPACE/docs
      #     poetry run python build_flash_parquets.py

      - name: Build Sphinx docs
        run: poetry run sphinx-build -b html $GITHUB_WORKSPACE/docs $GITHUB_WORKSPACE/_build

      - name: Cache build
        uses: actions/cache/save@v3
        id: save-cache
        with:
          path: |
            _build/
            docs/tutorial/*ipynb
            docs/tutorial/tutorial_checksums.txt
          key: ${{ runner.os }}-docs-build-${{ hashFiles('docs/tutorial/tutorial_checksums.txt') }}

      # upload the cache as artifact
      - name: Upload cache
        uses: actions/upload-artifact@v4
        with:
          path: |
            _build/
            docs/tutorial/*ipynb
            docs/tutorial/tutorial_checksums.txt

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: '_build'

  # deploy:
  #   environment:
  #     name: github-pages
  #     url: ${{ steps.deployment.outputs.page_url }}
  #   runs-on: ubuntu-latest
  #   needs: build
  #   steps:
  #     - name: Deploy to GitHub Pages
  #       id: deployment
  #       uses: actions/deploy-pages@v4