deploy.yml

# THIS FILE IS PART OF THE CYLC WORKFLOW ENGINE.
# Copyright (C) NIWA & British Crown (Met Office) & Contributors.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

# Deploy a new version of the documentation or rebuild an existing one.

# Note: All changes made to the gh-pages branch are non-destructive
#       (i.e. no force pushing) so all changes can be undone.

name: deploy

on:
  workflow_dispatch:
    inputs:
      cylc-flow-tag:
        description: 'Cylc Flow GitHub release tag (must be present in cylc-docs)'
        required: true
      cylc-rose-tag:
        description: 'cylc rose github release tag'
        required: true
      cylc-uis-tag:
        description: 'cylc uiserver github release tag'
        required: true
      metomi-rose-tag:
        description: 'Rose GitHub release tag (currently only affects cylc-rose install)'
        required: true
      set_stable:
        description: 'Stable build. Make this the default documented version.'
        type: boolean
        default: true
        required: false
      set_latest:
        description: 'Latest build (but not the default version). If the build is both the Latest and the Stable/default, use `set_stable` as well.'
        type: boolean
        default: true
        required: false
      skip_conda_environment_check:
        description: "Skip creation of conda environments"
        type: boolean
        default: false
        required: false

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        # use login shell for conda activation
        shell: bash -leo pipefail {0}
    steps:
      - name: configure python
        uses: actions/setup-python@v5
        with:
          python-version: '3.9'

      - name: configure git
        uses: cylc/release-actions/configure-git@v1

      - name: checkout cylc-doc
        uses: actions/checkout@v4
        with:
          ref: ${{ inputs.cylc-flow-tag }}
          path: docs

      - name: install dependencies
        uses: cylc/cylc-doc/.github/actions/install-dependencies@master

      - name: install cylc-doc
        working-directory: docs
        run: pip install ".[all]"

      - name: install libs
        uses: cylc/release-actions/install-cylc-components@v1
        with:
          cylc_flow: true
          cylc_flow_opts: 'main_loop-log_data_store,main_loop-log_db,main_loop-log_main_loop,main_loop-log_memory'
          cylc_flow_tag: ${{ inputs.cylc-flow-tag }}
          cylc_uiserver: true
          cylc_uiserver_opts: ''
          cylc_uiserver_tag: ${{ inputs.cylc-uis-tag }}
          cylc_rose: true
          cylc_rose_opts: ''
          cylc_rose_tag: ${{ inputs.cylc-rose-tag }}
          metomi_rose: true
          metomi_rose_opts: ''
          metomi_rose_tag: ${{ inputs.metomi-rose-tag }}

      - name: create conda envs
        uses: ./docs/.github/actions/create-conda-envs
        if: ${{ ! inputs.skip_conda_environment_check }}
        with:
          python_version: '3.9'
          working_directory: ./docs

      - name: checkout gh-pages
        uses: actions/checkout@v4
        with:
          ref: gh-pages
          path: gh-pages

      - name: sync static files
        if: ${{ inputs.set_stable }}
        env:
          DOCS: '${{ github.workspace }}/docs'
          PAGE: '${{ github.workspace }}/gh-pages'
        run: |
          rsync -r "$DOCS/doc/" "$PAGE/"

      - name: install gh-pages
        working-directory: docs
        run: |
          rm -r doc
          ln -s ../gh-pages doc

      - name: build docs
        run: |
          # NOTE: Doing a clean build allows up to update docs for a
          #       deployed version at a later date.
          make -C docs \
            clean \
            html \
            linkcheck \
            SPHINXOPTS='-Wn --keep-going' \
            FORCE_COLOR=true \
            STABLE=${{ inputs.set_stable }} \
            LATEST=${{ inputs.set_latest }}

      - name: debug - pip list
        if: failure()
        run: pip list

      - name: tidy old versions
        working-directory: docs
        run: |
          git rm -r $("./bin/version" tidy) || true

      - name: push changes
        working-directory: gh-pages
        run: |
          git add *
          git commit -m "add: ${{ inputs.cylc-flow-tag }}"
          git push origin HEAD