ci(docs): build the documentation in the official GDAL image

.github/workflows/docs_builder.yml

@@ -32,45 +32,36 @@
   group: "pages"
   cancel-in-progress: true
 
-env:
-  GDAL_VERSION: 3.*
-  PYTHON_VERSION: "3.11"
-
 jobs:
   build-docs:
     runs-on: ubuntu-24.04
+    # official GDAL image: libgdal and its Python bindings are already installed and
+    # version-matched, so no apt/PPA step and no GDAL compilation.
+    # Keep the tag aligned with GDAL_VERSION in the root Dockerfile.
+    container:
+      image: ghcr.io/osgeo/gdal:ubuntu-small-3.11.0
 
     steps:
       - name: Get source code
         uses: actions/checkout@v7
         with:
           persist-credentials: false
 
-      - name: Set up Python
-        uses: actions/setup-python@v7
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-          cache: "pip"
-          cache-dependency-path: pyproject.toml
-
-      - name: Install GDAL binaries
+      # the libraries after python3-tk are the system ones PyQt6 needs to be imported (GUI modules documented by autodoc)
+      - name: Install Python tooling, Tk and Qt system libraries
         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
+          apt-get update
+          apt-get install -y --no-install-recommends python3-pip python3-venv python3-tk libgl1 libegl1 libxkbcommon0 libdbus-1-3 libglib2.0-0t64
           gdal-config --version
 
-      - name: Install complementary tools
+      # --system-site-packages lets the venv see the image's pre-built osgeo bindings
+      - name: Create virtual environment
         run: |
-          sudo apt install python3-tk
+          python3 -m venv --system-site-packages /opt/venv
+          echo "/opt/venv/bin" >> "$GITHUB_PATH"
 
-      - name: Install project requirements
-        run: |
-          python -m pip install -U pip setuptools wheel
-          # Install GDAL first
-          python -m pip install GDAL=="`gdal-config --version`.*"
+      - name: Upgrade packaging tools
+        run: python -m pip install -U pip setuptools wheel
 
       # this job must run before installing other dependencies to avoid listing everything
       - name: Generates dependencies graph page with pipdetree
@@ -87,7 +78,8 @@
           pip-licenses --format=markdown --with-authors --with-description --with-urls --ignore-packages dicogis --output-file=docs/misc/licenses.md
 
       - name: Install project as a package
-        run: python -m pip install .[doc]
+        # gui extra: PyQt6 must be importable so autodoc can document dicogis.ui
+        run: python -m pip install .[doc,gui]
 
       - name: Build doc using Sphinx
         run: sphinx-build -b html -d docs/_build/cache -j auto -q docs docs/_build/html

docs/development/documentation.md

@@ -7,8 +7,8 @@ Project uses Sphinx to generate documentation from docstrings (documentation in-
 To build it:
 
 ```sh
-# install aditionnal dependencies
-python -m pip install .[doc]
+# install aditionnal dependencies (gui: PyQt6, needed to document dicogis.ui)
+python -m pip install .[doc,gui]
 # build it
 sphinx-build -b html docs docs/_build/html
 # optimized (quiet, multiprocessing, doctrees separated)