deploy-doc.yml

name: Deploy doc

on:
  workflow_call:
    inputs:
      doc-version:
        description: "Name of the doc version. The doc will be deployed to a subfolder with that name."
        required: true
        type: string
      doc-artifact-name:
        description: "Name of the artifact containing the built doc"
        required: false
        default: "doc"
        type: string
      doc-path:
        description: "Path where to extract the built doc"
        required: false
        default: "docs/build/html"
        type: string
      binder-env-fullref:
        description: "Full ref of the binder env to build. The build is triggered only if not empty."
        required: false
        default: ""
        type: string
jobs:
  trigger-binder-build:
    runs-on: ubuntu-latest
    if: inputs.binder-env-fullref != ''
    steps:
      - uses: actions/checkout@v4  # checkout triggering branch to get scripts/trigger_binder.sh
      - name: Trigger a build for default binder env ref on each BinderHub deployments in the mybinder.org federation
        run: |
          binder_env_full_ref=${{ inputs.binder-env-fullref }}
          echo Triggering binder environment build for ${binder_env_full_ref}
          bash scripts/trigger_binder.sh https://ovh.mybinder.org/build/gh/${binder_env_full_ref}
          bash scripts/trigger_binder.sh https://ovh2.mybinder.org/build/gh/${binder_env_full_ref}
          bash scripts/trigger_binder.sh https://notebooks.gesis.org/binder/build/gh/${binder_env_full_ref}

  deploy-doc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Download artifacts
        uses: actions/download-artifact@v4
        with:
          name: ${{ inputs.doc-artifact-name }}
          path: ${{ inputs.doc-path }}
      - name: Deploy documentation in a version subfolder on GH pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages # The branch the action should deploy to.
          folder: ${{ inputs.doc-path }} # The folder the action should deploy.
          target-folder: /${{ inputs.doc-version }} # The folder the action should deploy to.
          commit-message: publish documentation
          single-commit: true

  update-doc-versions:
    # update doc versions index if the doc has been deployed
    needs: [deploy-doc]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: gh-pages
      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      - name: Generate versions.json
        shell: python3 {0}
        run: |
          import json
          from pathlib import Path

          cwd = Path.cwd()
          versions = sorted((item.name for item in cwd.iterdir()
                             if item.is_dir() and not item.name.startswith('.')),
                            reverse=True)
          target_file = Path('versions.json')
          with target_file.open('w') as f:
              json.dump(versions, f)
      - name: Commit versions.json
        shell: bash
        run: |
          # Commit versions.json and squash it with previous commit
          git config user.name "Actions"
          git config user.email "actions@github.com"
          git add versions.json
          git commit --amend --no-edit
          git push -f origin gh-pages