coverage: 71.352% (+0.02%) from 71.33%
when pulling f635b66 on geographika:docstub-checks
into 76318b2 on OSGeo:master.

@dbaston - I've added a new python_stub_files target, and tested it on build-windows-conda in the "Build and test with CMake" action.

Output is:

Run cmake --build $GITHUB_WORKSPACE/build --config Release -j 2 --target python_stub_files
[0/2] Re-checking globbed directories...
[1/2] C:\Windows\system32\cmd.exe /C "cd /D D:\a\gdal\gdal\build\swig\python && C:\Users\runneradmin\miniconda3\envs\gdalenv\python.exe -m docstub run D:/a/gdal/gdal/build/swig/python/osgeo --config D:/a/gdal/gdal/build/swig/python/pyproject.toml"
1423 matched annotations
0 total errors

Finished in 15.446 s

I'll need some guidance on where this should be added in the CI, and default build options.

• A new CMake option BUILD_PYTHON_STUBS has been added, and set to OFF by default. I presume we don't want to set to ON until the stubs are useful?
• https://pypi.org/project/docstub/#files - only has docstub-0.4.0.tar.gz available - so there is no Windows option (apart from through conda).

Once finalised, I presume I should remove the ctest code?

@dbaston - I've tried a few different ways to add the stub building to CI but without success. The

• adding to ubuntu-22.04 in cmake_build.yml, needs to also install docstub (currently only in the docs/requirements.txt), but this only installs an older version 0.2.1 (I'm assuming to due to an older version of Python. --break-system-packages isn't supported when trying to run PYTHON_CMD=python3 && $PYTHON_CMD -m pip install docstub==0.5.0 --break-system-packages
• I also tried adding to linux_build.yml but I was unsure where any Python dependencies can / should be installed. .github/ubuntu_24.04/build.sh? I was unable to get a successful build.

IMHO I think it would be useful to keep the doc_checks.yml checks for the stubs. Any errors to stub generation will be caused by modifying the Python docstrings, so it falls into the documentation category. It might also be clearer to keep this failure rather than using a Linux build failure to highlight docstub issues. Ideally we'd have both the docs check and the CI build with docstubs - maybe this could be addressed in a separate PR?

Note - the current CI failure seems unrelated (I rolled back all recent CI changes).

I also tried adding to linux_build.yml but I was unsure where any Python dependencies can / should be installed.

dbaston@641e8e3 updates the Ubuntu 24.04 configuration to build the stubs. But a lot of warnings come out (https://github.com/dbaston/gdal/actions/runs/18979916443/job/54209573643#step:14:5542) which for some reason don't seem to block the build.

Ideally we'd have both the docs check and the CI build with docstubs - maybe this could be addressed in a separate PR?

That makes sense. My only request for the docs check piece would be to remove docstub from doc/requirements.txt and install it in doc_checks.yml.

That makes sense. My only request for the docs check piece would be to remove docstub from doc/requirements.txt and install it in doc_checks.yml.

Done.

But a lot of warnings come out (https://github.com/dbaston/gdal/actions/runs/18979916443/job/54209573643#step:14:5542)

Strange - this wasn't happening with the ctest. docstub 0.5.0 has been released since then - I'll check locally to see if I can recreate.

are we good to merge this PR or is there still something to be done?

OK to squash/merge as far as I'm concerned, we can sort out the build warnings in a subsequent PR.