ci_docs.yml

# Build and deploy documentation
#
# This workflow builds the documentation on Linux/macOS/Windows.
#
# It is run on every commit to the main and pull request branches, and also when a new
# release is published. In draft pull requests, only the job on Linux is triggered to
# save on Continuous Integration resources.
#
# On the main branch, the workflow also handles the documentation deployment:
#
# * Updating the development documentation by pushing the built HTML pages from the main
#   branch onto the dev folder of the gh-pages branch.
# * Updating the latest documentation link to the new release.
#
name: Docs

on:
  push:
    branches: [ main ]
    paths:
      - 'pygmt/**/*.py'
      - '!pygmt/tests/**'
      - 'doc/**'
      - 'examples/**'
      - 'README.md'
      - '.github/workflows/ci_docs.yml'
  pull_request:
    types: [opened, reopened, synchronize, ready_for_review]
    paths:
      - 'pygmt/**/*.py'
      - '!pygmt/tests/**'
      - 'doc/**'
      - 'examples/**'
      - 'README.md'
      - '.github/workflows/ci_docs.yml'
  workflow_dispatch:
  release:
    types:
      - published

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

permissions:
  contents: write

jobs:
  docs:
    name: ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    if: github.repository == 'GenericMappingTools/pygmt'
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        # Is it a draft Pull Request (true or false)?
        isDraft:
          - ${{ github.event.pull_request.draft }}
        # Only run jobs on Ubuntu for draft PRs
        exclude:
          - os: macos-latest
            isDraft: true
          - os: windows-latest
            isDraft: true
    timeout-minutes: 30
    defaults:
      run:
        shell: bash -l {0}
    env:
      # Tectonic cache directory.
      # See https://tectonic-typesetting.github.io/book/latest/getting-started/first-document.html#cache.
      TECTONIC_CACHE_DIR: ${{ github.workspace }}/.tectonic-cache

    steps:
      # Checkout current git repository
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Get current week number of year
        id: date
        run: echo "date=$(date +%Y-W%W)" >> $GITHUB_OUTPUT  # e.g., 2024-W19

      # Install Micromamba with conda-forge dependencies
      - name: Setup Micromamba
        uses: mamba-org/setup-micromamba@f457c30a868e4760d3a6fcea5f25dc655b8edf39 # v3.2.1
        with:
          environment-name: pygmt
          cache-environment: true
          # environment cache is persistent for one week.
          cache-environment-key: micromamba-environment-${{ steps.date.outputs.date }}
          create-args: >-
            python=3.15
            gmt=6.7.0
            ghostscript=10.08.0
            numpy
            pandas
            xarray
            packaging
            contextily
            geopandas
            ipython
            pyarrow-core
            rioxarray
            make
            pip
            python-build
            myst-nb
            panel
            sphinx>=6.2
            sphinx-autodoc-typehints
            sphinx-copybutton
            sphinx-design
            sphinx-gallery
            sphinx_rtd_theme
            cairosvg
            sphinxcontrib-svg2pdfconverter
            tectonic

      # Download cached remote files (artifacts) from GitHub
      - name: Download remote data from GitHub
        uses: $/.github/actions/download-gmt-cache

      # Install the package that we want to test
      - name: Install the package
        run: |
          python -m build --sdist
          python -m pip install dist/*

      - name: Build the HTML documentation
        env:
          GMT_DATA_SERVER: https://opentopography.s3.sdsc.edu/gmtdata
        run: |
          log_file="${RUNNER_TEMP}/sphinx-html.log"
          make -C doc clean html 2>&1 | tee "${log_file}"
          exit_code=${PIPESTATUS[0]}
          if [[ "${RUNNER_OS}" == "Windows" && "${exit_code}" -eq 2 ]] && grep -q "make: .* Error 2816" "${log_file}"; then
            echo "Sphinx HTML build exited with make error 2816 (segmentation fault) on Windows; allowing workflow to continue."
            exit 0
          fi
          exit "${exit_code}"

      - name: Cache tectonic packages
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 # zizmor: ignore[cache-poisoning]
        with:
          path: ${{ env.TECTONIC_CACHE_DIR }}
          # Cache is persistent for one week, same as the micromamba environment cache.
          key: tectonic-${{ runner.os }}-${{ steps.date.outputs.date }}
          # Fall back to the most recent cache so tectonic only downloads what's missing.
          restore-keys: tectonic-${{ runner.os }}-

      - name: Build the PDF documentation
        env:
          GMT_DATA_SERVER: https://opentopography.s3.sdsc.edu/gmtdata
        run: |
          log_file="${RUNNER_TEMP}/sphinx-pdf.log"
          make -C doc pdf 2>&1 | tee "${log_file}"
          exit_code=${PIPESTATUS[0]}
          if [[ "${RUNNER_OS}" == "Windows" && "${exit_code}" -eq 2 ]] && grep -q "make: .* Error 2816" "${log_file}"; then
            echo "Sphinx PDF build exited with make error 2816 (segmentation fault) on Windows; allowing workflow to continue."
            exit 0
          fi

      - name: Create the HTML ZIP archive and rename the PDF file
        run: |
          cd doc/_build/
          cp -r html/ pygmt-docs/
          zip -r pygmt-docs.zip pygmt-docs/
          mv latex/pygmt.pdf pygmt-docs.pdf
          cd ../..

      - name: Upload PDF as artifact for previewing on pull requests
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        if: github.event_name == 'pull_request' && matrix.os == 'ubuntu-latest'
        with:
          name: artifact-pygmt-docs-pdf
          path: doc/_build/pygmt-docs.pdf

      - name: Copy the HTML ZIP archive and PDF to the html folder
        run: cp -v doc/_build/pygmt-docs.zip doc/_build/pygmt-docs.pdf doc/_build/html/
        if: (github.event_name == 'push' || github.event_name == 'release') && matrix.os == 'ubuntu-latest'

      - name: Upload the HTML ZIP archive and PDF as release assets
        run: gh release upload ${REF_NAME} doc/_build/pygmt-docs.zip doc/_build/pygmt-docs.pdf
        if: github.event_name == 'release' && matrix.os == 'ubuntu-latest'
        env:
          GH_TOKEN: ${{ github.token }}
          REF_NAME: ${{ github.ref_name }}

      - name: Checkout the gh-pages branch
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: gh-pages
          # Checkout to this folder instead of the current one
          path: deploy
          persist-credentials: true
        if: (github.event_name == 'release' || github.event_name == 'push') && (matrix.os == 'ubuntu-latest')

      - name: Push the built HTML to gh-pages
        run: |
          # Detect if this is a release or from the main branch
          if [[ "${GITHUB_EVENT_NAME}" == "release" ]]; then
              # Get the tag name without the "refs/tags/" part
              version="${GITHUB_REF#refs/*/}"
          else
              version=dev
          fi
          echo "Deploying version: $version"
          # Make the new commit message. Needs to happen before cd into deploy
          # to get the right commit hash.
          message="Deploy $version from $(git rev-parse --short HEAD)"
          cd deploy
          # Create some files in the root directory.
          # .nojekyll: Need to have this file so that GitHub doesn't try to run Jekyll
          touch .nojekyll
          # CNAME: Set the custom domain name
          echo "www.pygmt.org" > CNAME
          # index.html: Redirect to the latest version
          echo '<meta http-equiv="Refresh" content="0;url=latest/"/>' > index.html
          # Delete all the files and replace with our new set
          echo -e "\nRemoving old files from previous builds of ${version}:"
          rm -rvf ${version}
          echo -e "\nCopying HTML files to ${version}:"
          cp -Rvf ../doc/_build/html/ ${version}/
          # If this is a new release, update the link from /latest to it
          if [[ "${version}" != "dev" ]]; then
              echo -e "\nSetup link from ${version} to 'latest'."
              rm -f latest
              ln -sf ${version} latest
          fi
          # Stage the commit
          git add -A .
          echo -e "\nChanges to be applied:"
          git status
          # Configure git to be the GitHub Actions account
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git config user.name "github-actions[bot]"
          # If this is a dev build and the last commit was from a dev build
          # (detect if "dev" was in the previous commit message), reuse the
          # same commit
          if [[ "${version}" == "dev" && `git log -1 --format='%s'` == *"dev"* ]]; then
              echo -e "\nAmending last commit:"
              git commit --amend --reset-author -m "$message"
          else
              echo -e "\nMaking a new commit:"
              git commit -m "$message"
          fi
          # Make the push quiet just in case there is anything that could leak
          # sensitive information.
          echo -e "\nPushing changes to gh-pages."
          git push -fq origin gh-pages 2>&1 >/dev/null
          echo -e "\nFinished uploading generated files."
        if: (github.event_name == 'release' || github.event_name == 'push') && (matrix.os == 'ubuntu-latest')