docs_builder.yml

name: "📚 Documentation Builder"

on:
  push:
    branches:
      - master
    paths:
      - "docs/**/*"
      - ".github/workflows/docs_builder.yml"
      - "dicogis/**/*.py"

    tags:
      - "*"

  pull_request:
    branches:
        - master
    paths:
      - ".github/workflows/docs_builder.yml"
      - docs/**/*
      - requirements/documentation.txt

  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

env:
  GDAL_VERSION: 3.*
  PYTHON_VERSION: "3.10"

jobs:
  build-docs:
    runs-on: ubuntu-latest

    steps:
      - name: Get source code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          cache: "pip"
          cache-dependency-path: "requirements/documentation.txt"

      - name: Install GDAL binaries
        run: |
          sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable && sudo apt-get update
          sudo apt install gdal-bin=${{ env.GDAL_VERSION }}
          sudo apt install libgdal-dev=${{ env.GDAL_VERSION }}
          export CPLUS_INCLUDE_PATH=/usr/include/gdal
          export C_INCLUDE_PATH=/usr/include/gdal
          gdal-config --version

      - name: Install complementary tools
        run: |
          sudo apt install python3-tk

      - name: Install project requirements
        run: |
          python -m pip install -U pip setuptools wheel
          # Install GDAL first
          python -m pip install GDAL=="`gdal-config --version`.*"
          # then project
          python -m pip install -U -r requirements/base.txt

      # this job must run before installing other dependencies to avoid listing everything
      - name: Generates dependencies graph page with pipdetree
        run: |
          python -m pip install -U "pipdeptree<3"
          echo -e "\`\`\`{mermaid}" > docs/misc/dependencies.md
          pipdeptree --exclude pip,pipdeptree,setuptools,wheel --mermaid >> docs/misc/dependencies.md
          echo -e "\`\`\`" >> docs/misc/dependencies.md

      # this job must run before installing other dependencies to avoid listing everything
      - name: Generates licenses page with pip-licences
        run: |
          python -m pip install -U "pip-licenses<5"
          pip-licenses --format=markdown --with-authors --with-description --with-urls --ignore-packages dicogis --output-file=docs/misc/licenses.md

      - name: Install documentation requirements
        run: |
          # python -m pip install -U -r requirements/development.txt
          python -m pip install -U -r requirements/documentation.txt

      - name: Install project as a package
        run: python -m pip install -e .[gdal]

      - name: Build doc using Sphinx
        run: sphinx-build -b html -d docs/_build/cache -j auto -q docs docs/_build/html

      - name: Save build doc as artifact
        uses: actions/upload-artifact@v4
        with:
          name: documentation
          path: docs/_build/html/*
          if-no-files-found: error
          retention-days: 30

      - name: Setup Pages
        uses: actions/configure-pages@v4
        if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/master')

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/master')
        with:
          # Upload entire repository
          path: docs/_build/html/

      - name: Deploy to GitHub Pages
        id: deployment
        if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/master')
        uses: actions/deploy-pages@v4