documentation.yml

---
name: Documentation

# Builds Markdown documentation for core and addons.

on:
  push:
    branches:
      - main
      - releasebranch_*
  pull_request:
  workflow_dispatch:

permissions: {}

jobs:
  ubuntu:
    concurrency:
      group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.head_ref || github.sha }}
      cancel-in-progress: true

    runs-on: ubuntu-24.04
    env:
      PYTHONWARNINGS: always
      # renovate: datasource=python-version depName=python
      PYTHON_VERSION: "3.14"

    steps:
      - name: Checkout core
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          path: grass
          fetch-depth: 0
          persist-credentials: false

      - name: Get dependencies
        run: |
          sudo apt-get update -y
          sudo apt-get install -y wget git gawk findutils \
            doxygen \
            gettext \
            graphviz \
            libpq-dev \
            unixodbc-dev
          LC_ALL=C.UTF-8 sudo add-apt-repository -y ppa:ubuntugis/ubuntugis-unstable
          sudo apt-get update -y
          xargs -a <(awk '! /^ *(#|$)/' "grass/.github/workflows/apt.txt") -r -- \
              sudo apt-get install -y --no-install-recommends --no-install-suggests

      - name: Set up Python (with cache)
        if: ${{ contains(fromJSON('["push", "pull_request"]'), github.event_name) }}
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          cache: pip # zizmor: ignore[cache-poisoning] Assuming push event is not used for tags

      - name: Set up Python (no cache, use for release artifacts)
        if: ${{ !contains(fromJSON('["push", "pull_request"]'), github.event_name) }}
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Set version variables
        run: |
          cd grass || exit
          eval "$(./utils/update_version.py status --bash)"
          {
            echo "MAJOR=${MAJOR}"
            echo "MINOR=${MINOR}"
            echo "VERSION=${VERSION}"
            echo "YEAR=${YEAR}"
          } >> "${GITHUB_ENV}"

      - name: Checkout addons
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          repository: OSGeo/grass-addons
          ref: grass${{ env.MAJOR }}
          path: grass-addons
          fetch-depth: 0
          persist-credentials: false

      - name: ccache (do not use for release artifacts)
        uses: hendrikmuhs/ccache-action@5ebbd400eff9e74630f759d94ddd7b6c26299639 # v1.2.20
        if: ${{ !contains(fromJSON('["push", "pull_request"]'), github.event_name) }}
        with:
          create-symlink: true
          verbose: 2
          evict-old-files: 7d
          key: ${{ github.workflow }}-${{ github.job }}-grass${{ env.MAJOR }}-${{ env.PYTHON_VERSION }}

      - name: Install Python dependencies
        # We install both core and addon dependencies, but we don't install any
        # dependencies from the extra list in addons because we don't actually
        # run them (and they should be lazy-imported).
        run: |
          pip install -r grass/.github/workflows/python_requirements.txt
          pip install -r grass-addons/.github/workflows/requirements.txt

      - uses: rui314/setup-mold@725a8794d15fc7563f59595bd9556495c0564878 # v1
        if: ${{ !contains(fromJSON('["push", "pull_request"]'), github.event_name) }}

      - name: Create installation directory
        run: |
          mkdir "$HOME/install"

      - name: Set number of cores for compilation
        run: |
          echo "MAKEFLAGS=-j$(nproc)" >> "$GITHUB_ENV"

      - name: Set LD_LIBRARY_PATH for compilation
        run: |
          echo "LD_LIBRARY_PATH=$HOME/install/lib" >> "$GITHUB_ENV"

      - name: Build core
        run: |
          cd grass
          export INSTALL_PREFIX="$HOME/install"
          ./configure \
            --enable-largefile \
            --prefix="$INSTALL_PREFIX/" \
            --with-blas \
            --with-bzlib \
            --with-cxx \
            --with-fftw \
            --with-freetype \
            --with-freetype-includes="/usr/include/freetype2/" \
            --with-geos \
            --with-lapack \
            --with-libsvm \
            --with-netcdf \
            --with-nls \
            --with-odbc \
            --with-openmp \
            --with-pdal \
            --with-postgres --with-postgres-includes=/usr/include/postgresql \
            --with-proj-share=/usr/share/proj \
            --with-pthread \
            --with-readline \
            --with-sqlite \
            --with-tiff \
            --with-zstd
          make
          make install

      - name: Add the bin directory to PATH
        run: |
          echo "$HOME/install/bin" >> "$GITHUB_PATH"

      - name: Print installed versions
        if: always()
        run: ./grass/.github/workflows/print_versions.sh

      - name: Test executing of the grass command
        run: ./grass/.github/workflows/test_simple.sh

      - name: Build Programmer's Manual with doxygen
        run: |
          cd grass
          make htmldocs

      - name: Make the doxygen results available (html)
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: doxygen-site
          if-no-files-found: error
          path: |
            grass/html
            !grass/html/**.map
            !grass/html/**.md5
          retention-days: 3

      - name: Make the doxygen results available (latex)
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: doxygen-site-latex
          if-no-files-found: error
          path: |
            grass/latex
            !grass/latex/**.map
            !grass/latex/**.md5
          retention-days: 3
      - name: Compile addons
        run: |
          ./grass-addons/utils/cronjobs_osgeo_lxd/compile_addons_git.sh \
            "${MAJOR}" \
            "${MINOR}" \
            "$(pwd)/grass-addons/src" \
            "$(grass --config path)" \
            "$(pwd)/addons-build-dir" \
            grass

      - name: Get target path for Markdown files
        run: |
          echo MKDOCS_DIR="$(grass --config path)/docs/mkdocs" >> "$GITHUB_ENV"

      - name: Move from build to target directory
        run: |
          mkdir "${MKDOCS_DIR}/source/addons"
          mv -v addons-build-dir/docs/md/source/* "${MKDOCS_DIR}/source/addons"

      - name: Build index
        run: |
          ARCH="$(grass --config arch)"
          ARCH_DISTDIR="$(grass --config path)"
          export ARCH
          export ARCH_DISTDIR
          export VERSION_NUMBER="${VERSION}"
          grass --tmp-project XY --exec \
            python grass/man/build_full_index.py md index "${MKDOCS_DIR}/source/addons" addons

      - name: Copy shared files to addons
        run: |
          cd "${MKDOCS_DIR}/source" || exit
          # This should match directories with color tables and other files
          # linked from the pages.
          # shellcheck disable=SC2010,SC2035 # TODO: Address these two issues
          for name in $(ls -1d */ | grep -vE "^(addons|libpython)/$"); do
            cp -rv "${name}" addons
          done

      - name: Get mkdocs
        run: |
          pip install -r "grass/man/mkdocs/requirements.txt"

      - name: Run mkdocs
        run: |
          cd grass || exit
          eval "$(./utils/update_version.py status --bash)"
          cd ..
          export SITE_NAME="GRASS $VERSION Documentation"
          export COPYRIGHT="&copy; 2003-$YEAR GRASS Development Team, GRASS $VERSION Documentation"
          cd "${MKDOCS_DIR}" || exit
          mkdocs build

      - name: Build Sphinx documentation
        run: |
          pip install -r "grass/python/grass/docs/requirements.txt"
          cd grass || exit
          make sphinxdoclib
          ARCH="$(grass --config arch)"
          mv -v dist."${ARCH}/docs/html/libpython" "${MKDOCS_DIR}/site"

      - name: Merge Sphinx and MkDocs Sitemaps
        run: |
          cd grass || exit
          python utils/merge_sitemaps.py \
            --mkdocs-sitemap "${MKDOCS_DIR}/site/sitemap.xml" \
            --sphinx-sitemap "${MKDOCS_DIR}/site/libpython/sitemap.xml" \
            --output "${MKDOCS_DIR}/site/sitemap.xml" \
            --version "${VERSION}" -o

      - name: Make logs available
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: grass-addon-build-logs
          if-no-files-found: error
          path: addons-build-dir/logs
          retention-days: 3

      - name: Make the result available
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: mkdocs-site
          if-no-files-found: error
          path: ${{ env.MKDOCS_DIR }}/site
          retention-days: 3