docs.yml

#
# Build GMT documentation and deploy
#
name: Docs

on:
  # pull_request:
  push:
    branches:
      - master
      - 6.[0-9]+
    paths:
      - 'ci/**'
      - 'doc/**'
      - '**/CMakeLists.txt'
      - '.github/workflows/docs.yml'
  release:
    types:
      - published

defaults:
  run:
    # default to use bash shell
    shell: bash -el {0}

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}

jobs:
  docs:
    name: ${{ matrix.name }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 45

    env:
      # directories
      COASTLINEDIR: ${{ github.workspace }}/coastline
      INSTALLDIR: ${{ github.workspace }}/gmt-install-dir
      # disable auto-display of GMT plots
      GMT_END_SHOW: off
      # Build documentation
      BUILD_DOCS  : true
      PACKAGE     : true
      RUN_TESTS   : false

    strategy:
      fail-fast: false
      matrix:
        include:
          - name: Linux
            os: ubuntu-latest
          - name: macOS
            os: macos-latest
          - name: Windows
            os: windows-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4.2.2

      - name: Setup vcpkg (Windows)
        run: gh run download -n vcpkg-cache -D C:/vcpkg/installed/
        if: runner.os == 'Windows'
        env:
          GH_TOKEN: ${{ github.token }}

      - name: Setup conda (macOS)
        uses: conda-incubator/setup-miniconda@v3
        if: runner.os == 'macOS'

      - name: Install GMT dependencies
        run: |
          # $RUNNER_OS can be Linux, macOS or Windows
          # The following command converts $RUNNER_OS to lowercase
          os=$(echo "$RUNNER_OS" | tr '[:upper:]' '[:lower:]')
          bash ci/install-dependencies-${os}.sh

      - name: Download GSHHG and DCW data
        run: gh run download -n coastline-cache -D coastline
        env:
          GH_TOKEN: ${{ github.token }}

      - name: Pull baseline image data from dvc remote
        run: dvc pull --no-run-cache

      - name: Configure GMT
        run: |
          if [ "$RUNNER_OS" != "Windows" ]; then
            bash ci/config-gmt-unix.sh
          else
            bash ci/config-gmt-windows.sh
          fi

      - name: Compile GMT (Linux/macOS)
        run: |
          mkdir build
          cd build
          cmake -G Ninja ..
          cmake --build .
        if: runner.os != 'Windows'

      - name: Compile GMT (Windows)
        shell: cmd
        run: |
          mkdir build
          cd build
          call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
          cmake -G Ninja .. -DCMAKE_TOOLCHAIN_FILE=%VCPKG_INSTALLATION_ROOT%\scripts\buildsystems\vcpkg.cmake -DCMAKE_BUILD_TYPE=Release
          cmake --build .
        if: runner.os == 'Windows'

      - name: Build documentation
        run: |
          set -x -e
          cd build
          cmake --build . --target docs_depends
          if [ -x "$(command -v pngquant)" ]; then  # optional step
            cmake --build . --target optimize_images
          fi
          cmake --build . --target docs_html
          # if html.log isn't empty (i.e., sphinx raise warnings), return 1
          ! [ -s doc/rst/html.log ]
          cmake --build . --target docs_man
          # Show warnings saved in html.log and man.log but filter out "duplicate label" warnings.
          # See https://github.com/GenericMappingTools/gmt/issues/7253
          grep -v 'WARNING: duplicate label -' doc/rst/html.log

      - name: Install GMT
        run: |
          cd build
          cmake --build . --target install
          # Add GMT PATH to bin
          echo "${INSTALLDIR}/bin" >> $GITHUB_PATH

      - name: Checkout the gh-pages branch in a separate folder
        uses: actions/checkout@v4.2.2
        with:
          ref: gh-pages
          # Checkout to this folder instead of the current one
          path: deploy
          # Download the entire history
          fetch-depth: 0
        if: github.event_name != 'pull_request' && matrix.os == 'ubuntu-latest'

      - name: Deploy documentation to GitHub
        run: bash ci/deploy-gh-pages.sh
        if: github.event_name != 'pull_request' && matrix.os == 'ubuntu-latest'

      - name: Package GMT
        run: |
          set -x -e
          cd build
          cmake --build . --target gmt_release
          cmake --build . --target gmt_release_tar
          if [ "$RUNNER_OS" = "macOS" ]; then
            # Create macOS bundle
            cpack -G Bundle
          elif [ "$RUNNER_OS" = "Windows" ]; then
            # Don't use cpack here. Chocolatey also provides a cpack command.
            cmake --build . --target package
          fi