docs-deploy.yml

on:
  workflow_call:
    inputs:
      deploy_type:
        description: "What type of doc deployment to undertake, option of: [test, update_latest, update_stable]"
        required: true
        type: string
      development_version_name:
        description: "The name of the docs version which follows the project's `main` branch builds, i.e., not linked to a versioned release."
        required: false
        type: string
        default: develop
      notebook_kernel:
        description: "If jupyter notebooks are included in the docs, specify the kernel name they expect, e.g. the package name"
        required: false
        type: string
      additional_mamba_args:
        description: "Any additional arguments to pass to micromamba when creating the python environment"
        required: false
        default: ""
        type: string
      py3version:
        description: "Minor version of Python version 3 to run the test on (e.g. `11` for python v3.11)"
        required: false
        type: string
        default: "11"

defaults:
  run:
    shell: bash -l {0}

jobs:
  docs-deploy:
    runs-on: ubuntu-latest
    steps:

    - uses: actions/checkout@v4
      id: branch-exists
      with:
        path: tmp/gh-pages
        ref: gh-pages
      continue-on-error: true

    - uses: actions/checkout@v4
      with:
        fetch-depth: 0  # used to build docs into the gh-pages branch without losing branch history. See https://github.com/jimporter/mike/issues/49

    - uses: arup-group/actions-city-modelling-lab/.github/actions/create-mamba-env@main
      with:
        py3version: ${{ inputs.py3version }}
        env_name: docs
        additional_mamba_args: ${{ inputs.additional_mamba_args }}
        cache_mamba_env: "true"

    - name: install jupyter kernel
      if: inputs.notebook_kernel != ''
      run: python -m ipykernel install --user --name ${{ inputs.notebook_kernel }}

    - name: Setup doc deploy
      run: |
        git config --global user.name Docs deploy
        git config --global user.email docs@dummy.bot.com

    - name: Test that docs build
      if: inputs.deploy_type == 'test'
      run: mike deploy ${{ inputs.development_version_name }}

    - name: Link development version to `latest` in documentation
      if: inputs.deploy_type == 'update_latest' && steps.branch-exists.outcome == 'failure' && inputs.development_version_name != 'latest'
      run: mike deploy --push --update-aliases ${{ inputs.development_version_name }} latest

    - name: Initialise latest as default version in documentation
      if: inputs.deploy_type == 'update_latest' && steps.branch-exists.outcome == 'failure'
      run: mike set-default --push latest

    - name: Deploy latest docs to gh-pages branch
      if: inputs.deploy_type == 'update_latest'
      run: mike deploy --push ${{ inputs.development_version_name }}

    - name: Deploy stable docs to gh-pages branch
      if: inputs.deploy_type == 'update_stable'
      run: |
        mike deploy --push ${{ github.ref_name }}
        mike deploy --push --update-aliases ${{ github.ref_name }} stable
        mike set-default --push stable