docs.yml

# Build the main or dev websites

#########
# IMPORTANT: it is also responsible for merging the `tmp_evaluated_fghgf_{PRBranchName}` branch
# into `evaluated` and PUSHING that change to `evaluated`.
# This happens whenever a PR is merged.
########

# Runs on:
# - merged PRs: merge `tmp_evaluated_fghgf_{PRBranchName}` into`evaluated 
#   ,push to `evaluated` and build main site
# - workflow_call (from pr_flow.yml):
#   - at least one project built: pull the `tmp_evaluated_fghgf_{PRBranchName}`
#     and `evaluated` branches, merge locally (NOT pushed), and build the dev site
#   - no project built, checkout `evaluated` and build main site
# - workflow_dispatch: checkout `evaluated` and build main or dev site
# - schedule: checkout `evaluated`, don't build any site

name: docs

on:
  pull_request:
    branches:
      - "main"
    types:
      - closed
  workflow_call:
    inputs:
      target:
        description: Site to build and deploy, dev or main
        type: string
        required: true
        default: dev
      branch:
        description: Branch suffix to pull the evaluated projects from
        type: string
        required: true
        default: ''
      type:
        description: hack
        required: true
        type: string
      changedprojects:
        description: Projects that have been built on the temp branch
        type: string
        required: false
      removedprojects:
        description: Projects that should be removed
        type: string
        required: false
  workflow_dispatch:
    inputs:
      target:
        description: Site to build and deploy
        type: choice
        options:
        - dev
        - main
        - dryrun
        required: true
        default: dryrun
  schedule:
    - cron: '0 2 * * SUN'

permissions:
  # To allow the workflow to push to the origin, when actions/checkout is used.
  contents: write
  # To allow the workflow to submit a comment using thollander/actions-comment-pull-request
  pull-requests: write

jobs:
  build_docs:
    # On merged PRs, workflow_call (pull_request event) or other events that can trigger this workflow (see above)
    if: github.event_name != 'pull_request' || (github.event_name == 'pull_request' && inputs.type == 'workflow_call')  || github.event.pull_request.merged == true 
    name: Documentation
    runs-on: 'ubuntu-latest'
    timeout-minutes: 30
    defaults:
      run:
        shell: bash -el {0}
    steps:
    - uses: actions/checkout@v4
      with:
        # Needed to compute the diff between the head and the latest commit on main (so at least 2)
        # AND needed to compute last_updated
        fetch-depth: 0
    # - uses: hmarr/debug-action@v2
    - name: debug
      run: |
        echo ${{ github.ref_name }}
        echo ${{ github.event_name }}
        echo ${{ inputs.type }}
        echo ${{ inputs.branch }}
    - uses: conda-incubator/setup-miniconda@v3
      with:
        miniconda-version: "latest"
        auto-activate-base: false
        activate-environment: examples-gallery-manage
        environment-file: envs/environment-ubuntu-latest.lock
    - name: infer evaluated branch name and deployment target
      id: set-vars
      run: |
        EVENTNAME="${{ github.event_name }}"
        # Called by pr_flow.yml, uses the tmp evaluated branch,
        # github.event_name doesn't matter as we're using inputs.type to
        # define the context.
        if [ "${{ inputs.type }}" == "workflow_call" ]; then
          NAME="tmp_evaluated_fghgf_${{ inputs.branch }}"
          TARGET="dev"
        # Merged PRs, use the evaluated branch
        elif [ "$EVENTNAME" == "pull_request" -a "${{ github.event.pull_request.merged }}" == "true" ]; then
          NAME="tmp_evaluated_fghgf_${{ github.event.pull_request.head.ref }}"
          TARGET="main"
        elif [ "$EVENTNAME" == "workflow_dispatch" ]; then
          NAME="evaluated"
          TARGET="${{ inputs.target }}"
        elif [ "$EVENTNAME" == "schedule" ]; then
          NAME="evaluated"
          # schedule events do not deploy a dev site, they're dry run
          TARGET=""
        fi
        echo "Evaluated branch: $NAME"
        echo "Target: $TARGET"
        echo "NAME=$NAME" >> $GITHUB_OUTPUT
        echo "TARGET=$TARGET" >> $GITHUB_OUTPUT
    - name: sync evaluated on merged PRs
      # The `evaluated` branch is only updated when a PR is merged.
      if: github.event_name == 'pull_request' && github.event.pull_request.merged == true 
      run: |
        # We are on 'main' and the PR has just been merged into it.
        # We need to:
        # - find out which projects were changed/removed. If none, there's nothing to do, skip.
        # - if some projects changed:
        #    - checkout the evaluated branch
        #    - add to that branch the projects than changed (we do it from the dev temp branch
        #      but could also do it from the main branch)
        #    - commit changes to evaluated
        #    - delete the dev tmp branch
        #    - checkout main back

        git config user.email "github-actions@github.com"
        git config user.name "github-actions"

        # git fetch and git diff
        CHANGES=$(doit util_list_changed_dirs_with_last_commit --exclude-website-metadata --exclude-deployments-metadata --exclude-test-data | tail -n -1)

        CHANGEDPROJECTS=$(echo $CHANGES | jq -c -r '.changed')
        REMOVEDPROJECTS=$(echo $CHANGES | jq -c -r '.removed')

        if [ "$CHANGEDPROJECTS" != "[]" -a "$REMOVEDPROJECTS" != "[]" ]; then
          echo "No support for removing and updating projects together"
          echo "Open a PR that just remove project"
          exit 1
        fi

        if [ "$CHANGEDPROJECTS" != "[]" ]; then

          # Some changes were made, the evaluated branch needs to be updated
          # with new data stored in the tmp dev branch.

          DEVBRANCH=${{ steps.set-vars.outputs.name }}
          echo "Projects changed since last commit on main: $CHANGEDPROJECTS"
          echo "Merging the $DEVBRANCH branch into the evaluated branch "
          git fetch https://github.com/${GITHUB_REPOSITORY}.git evaluated:refs/remotes/evaluated
          git fetch https://github.com/${GITHUB_REPOSITORY}.git $DEVBRANCH:refs/remotes/$DEVBRANCH
          echo "Checkout the evaluated branch"
          git checkout evaluated
          git checkout -b evaluated
          # Important: assumes there's no whitespace in the project names
          echo "Parse projects to remove them"
          items=$(echo $CHANGEDPROJECTS | jq -c -r '.[]')
          for item in ${items[@]}; do
              echo "Removing doc/gallery/$item..."
              rm -rf doc/gallery/$item/
              echo "Removed doc/gallery/$item"
          done
          echo "Pull evaluated docs from the dev branch"
          git checkout $DEVBRANCH -- doc/gallery/
          git diff --name-only
          git add './doc/gallery/'
          git commit -m "Add $CHANGEDPROJECTS"
          git log -n 10 --oneline
          echo "Push changes to evaluated"
          git push origin HEAD:evaluated
          echo "Delete the dev evaluated branch $DEVBRANCH"
          git push origin --delete $DEVBRANCH
          git checkout main
        elif [ "$REMOVEDPROJECTS" != "[]" ]; then

          # One of more projects have been removed, they need to be removed from
          # the evaluated branch.

          git fetch https://github.com/${GITHUB_REPOSITORY}.git evaluated:refs/remotes/evaluated
          echo "Checkout the evaluated branch"
          git checkout evaluated
          git checkout -b evaluated
          echo "Parse projects to remove them"
          items=$(echo $REMOVEDPROJECTS | jq -c -r '.[]')
          for item in ${items[@]}; do
              echo "Removing doc/gallery/$item..."
              rm -rf doc/gallery/$item/
              echo "Removed doc/gallery/$item"
              git add ./doc/gallery/$item
          done
          git commit -m "Remove $REMOVEDPROJECTS"
          git log -n 10 --oneline
          echo "Push changes to evaluated"
          git push origin HEAD:evaluated
        fi
    - name: checkout evaluated
      # any event that isn't workflow_call (coming from pr_flow.yml)
      # workflow_call events that didn't update any project at all
      if: inputs.type != 'workflow_call' || (inputs.type == 'workflow_call' && inputs.changedprojects == '[]')
      run: |
        # Work from a temporary branch
        git checkout -b deploy--temp-asdfghjkl
        git fetch https://github.com/${GITHUB_REPOSITORY}.git evaluated:refs/remotes/evaluated
        # Checkout only the /doc/gallery folder than contains the evaluated artefacts
        git checkout evaluated -- ./doc/gallery
        tree doc/gallery -L 2
    - name: sync dev evaluated
      # workflow_call events (coming from pr_flow.yml) that did update at least one project
      if: inputs.type == 'workflow_call' && (inputs.changedprojects != '[]' || inputs.removedprojects != '[]' )
      run: |
        CHANGEDPROJECTS='${{ inputs.changedprojects }}'
        REMOVEDPROJECTS='${{ inputs.removedprojects }}'

        git config user.email "github-actions@github.com"
        git config user.name "github-actions"

        if [ "$CHANGEDPROJECTS" != "[]" ]; then

          # We setup the repo so that it has the doc from the dev evaluated branch
          # and from the evaluated branch

          echo "Merging the $DEVBRANCH branch into the evaluated branch "
          DEVBRANCH=${{ steps.set-vars.outputs.name }}
          git fetch https://github.com/${GITHUB_REPOSITORY}.git evaluated:refs/remotes/evaluated
          git fetch https://github.com/${GITHUB_REPOSITORY}.git $DEVBRANCH:refs/remotes/$DEVBRANCH
          git fetch https://github.com/${GITHUB_REPOSITORY}.git ${{ inputs.branch }}:refs/remotes/${{ inputs.branch }}
          git fetch https://github.com/${GITHUB_REPOSITORY}.git main:refs/remotes/main
          git checkout evaluated
          git checkout -b evaluated
          # Important: assumes there's no whitespace in the project names
          echo "Parse projects to remove them"
          items=$(echo $CHANGEDPROJECTS | jq -c -r '.[]')
          for item in ${items[@]}; do
              echo "Removing doc/gallery/$item..."
              rm -rf doc/gallery/$item/
              echo "Removed doc/gallery/$item"
          done
          # Checkout only the /doc/gallery folder than contains the evaluated artefacts
          # we want to add to the evaluated branch, albeit just temporarily for this docs build
          git checkout $DEVBRANCH -- doc/gallery/
          git diff --name-only
          # This isn't meant to be pushed, it's just for this docs build
          git add './doc/gallery/'
          git commit -m "Add $CHANGEDPROJECTS"
          git checkout ${{ inputs.branch }}
          # Checkout only the /doc/gallery folder than contains the evaluated artefacts
          git checkout evaluated -- ./doc/gallery
          git diff --name-only
          git log -n 10 --oneline
          tree doc/gallery -D -h
          ls
        elif [ "$REMOVEDPROJECTS" != "[]" ]; then

          # We setup the repo so that it has the doc from the dev evaluated branch
          # and from the evaluated branch

          git fetch https://github.com/${GITHUB_REPOSITORY}.git evaluated:refs/remotes/evaluated
          git fetch https://github.com/${GITHUB_REPOSITORY}.git ${{ inputs.branch }}:refs/remotes/${{ inputs.branch }}
          git fetch https://github.com/${GITHUB_REPOSITORY}.git main:refs/remotes/main
          git checkout evaluated
          git checkout -b evaluated
          # Important: assumes there's no whitespace in the project names
          echo "Parse projects to remove them"
          items=$(echo $REMOVEDPROJECTS | jq -c -r '.[]')
          for item in ${items[@]}; do
              echo "Removing doc/gallery/$item..."
              rm -rf doc/gallery/$item/
              echo "Removed doc/gallery/$item"
              git add ./doc/gallery/$item
          done
          git diff --name-only
          # This isn't meant to be pushed, it's just for this docs build
          git commit -m "Remove $REMOVEDPROJECTS"
          git checkout ${{ inputs.branch }}
          # Checkout only the /doc/gallery folder than contains the evaluated artefacts
          git checkout evaluated -- ./doc/gallery
          git diff --name-only
          git log -n 10 --oneline
          tree doc/gallery -D -h
          ls
        fi
    - name: archive projects
      run: doit doc_archive_projects
    - name: move content
      run: doit doc_move_content
    - name: "temp: remove non evaluated projects"
      run: doit doc_remove_not_evaluated
    - name: generate deployments JSON
      run: doit doc_deployments
    - name: build dev website
      if: steps.set-vars.outputs.target == 'dev'
      env:
        EXAMPLES_HOLOVIZ_DEV_SITE: 'true'
      run: doit doc_build_website
    - name: build main website
      if: steps.set-vars.outputs.target == 'main'
      run: doit doc_build_website
      # ZIP and upload the built site:
      # Only when called from pr_flow.yml. Done as multiple PRs can update the dev website
      # concurrently, this offers a way to download the site and see it locally.
    # - name: tar built site
    #   if: inputs.type == 'workflow_call'
    #   run: tar czf builtdocs.tar.gz builtdocs/
    # - uses: actions/upload-artifact@v3
    #   if: inputs.type == 'workflow_call'
    #   with:
    #     name: website
    #     path: builtdocs.tar.gz
    #     retention-days: 3
    # - name: delete zip
    #   if: inputs.type == 'workflow_call'
    #   run: rm builtdocs.tar.gz
    - name: Deploy dev
      # workflow_call, by pr_flow.yml
      # workflow_dispatch and dev target
      if: steps.set-vars.outputs.target == 'dev'
      uses: peaceiris/actions-gh-pages@v3
      with:
        personal_token: ${{ secrets.ACCESS_TOKEN }}
        external_repository: holoviz-dev/examples
        publish_dir: ./builtdocs
        force_orphan: true
    - name: Deploy main
      # merged PR
      # workflow_dispatch and main target
      if: steps.set-vars.outputs.target == 'main'
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./builtdocs
        cname: examples.holoviz.org
        force_orphan: true
    - name: Clean up
      run: doit clean --clean-dep doc_full
      # TODO: re-enable git diff --quiet --exit-code
    # - name: Check clean up
    #   run: git diff
    # - name: Check clean up
    #   run: git diff --quiet --exit-code
    - name: Comment PR
      # Only display the comment in a pr_flow context
      if: inputs.type == 'workflow_call'
      uses: thollander/actions-comment-pull-request@v3
      with:
        message: 'Your changes were successfully integrated in the <a href="https://holoviz-dev.github.io/examples/" target="_blank">dev site</a>, make sure to review the pages of the projects you touched before merging this PR.'