documentation.yml

name: documentation
on:
  # Triggers the workflow on push but only for the main branch
  push:
    branches: [ main ]
    tags: [ v* ]
    paths:
      - sed/**/*
      - tutorial/**
      - .github/workflows/documentation.yml
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:


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'

      #  Check out repo and set up Python
      - name: Check out the repository
        uses: actions/checkout@v4
        with:
          lfs: true

      # Use cached python and dependencies, install poetry
      - name: "Setup Python, Poetry and Dependencies"
        uses: packetcoders/action-setup-cache-python-poetry@main
        with:
          python-version: 3.9
          poetry-version: 1.8.3

      - 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

      # rm because hextof_workflow notebook can not run outside maxwell
      - name: copy tutorial files to docs
        run: |
          cp -r $GITHUB_WORKSPACE/tutorial $GITHUB_WORKSPACE/docs/
          cp -r $GITHUB_WORKSPACE/sed/config $GITHUB_WORKSPACE/docs/sed
          rm $GITHUB_WORKSPACE/docs/tutorial/5_sxp_workflow.ipynb


      - name: download RAW data
        # if: steps.cache-primes.outputs.cache-hit != 'true'
        run: |
          cd $GITHUB_WORKSPACE/docs
          poetry run python scripts/download_data.py

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

      # to be removed later. This theme doesn't support <3.9 python and our lock file contains 3.8
      - name: install pydata-sphinx-theme
        run: |
          poetry run pip install pydata-sphinx-theme

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

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: sphinx-docs
          path: _build

  # this job pushes the built documentation to the docs repository
  push:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Checkout docs repo
        uses: actions/checkout@v2
        with:
          repository: ${{ github.repository_owner }}/docs
          token: ${{ secrets.GITHUB_TOKEN }}
          path: 'docs-repo'

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.9.0
        with:
          ssh-private-key: ${{ secrets.SSH_DOCS_DEPLOY_KEY }}

      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: sphinx-docs
          path: sphinx-docs

      - name: Determine version folder
        id: version-folder
        run: |
          if [[ $GITHUB_REF == refs/tags/* ]]; then
            VERSION=${GITHUB_REF#refs/tags/}
            echo "folder=sed/$VERSION" >> $GITHUB_OUTPUT
          else
            echo "folder=sed/latest" >> $GITHUB_OUTPUT
          fi

      - name: Copy documentation to the right version folder
        run: |
          mkdir -p docs-repo/${{ steps.version-folder.outputs.folder }}
          cp -r sphinx-docs/* docs-repo/${{ steps.version-folder.outputs.folder }}
          rm -rf docs-repo/${{ steps.version-folder.outputs.folder }}/.doctrees
          rm -rf docs-repo/${{ steps.version-folder.outputs.folder }}/tutorial/*.ipynb

      - name: Push changes
        run: |
          cd docs-repo
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add .
          git commit -m "Update documentation"
          git push