Doc building: import GDAL Python bindings early

[rouault]

We don't strictly need to import them at the beginning of conf.py, but importing them early helps in having a better error message if they cannot be imported rather than waiting later when autodoc tries to load them

In my case, this was due to an obscure situation. My libgdal.so in my build tree links to a /path/to/install-libjpeg-turbo/lib/libjpeg.so.8, with it being libjpeg-turbo 3.0 with new symbols. That full path to libjpeg is embedded in libgdal.so, but /path/to/install-libjpeg-turbo/lib was not pointed in LD_LIBRARY_PATH.
This worked fine when doing "from osgeo import gdal" from a 'regular' Python interpreter, or running pytest. But strangely, this failed within the sphinx-build process. The autodoc error message wasn't helpful just saying it couldn't import the osgeo module, whereas if trying to import in conf.py I got an exception pointing to the fact a symbol from libjpeg.so couldn't be loaded. I suspect that something in the sphinx-build process loads the system libjpeg library, that does not have the new symbols of libjpeg-turbo 3.0 that my libgdal.so was using, hence causing later loading of libgdal to fail.

Now that I've added /path/to/install-libjpeg-turbo/lib in LD_LIBRARY_PATH, things work and this patch isn't actually needed, but it may help diagnose further similar situations

CC @dbaston

[dbaston]

I would be hesitant about messing up the doc build for a casual contributor who wants to tests a change to another part of the docs and doesn't have the Python bindings set up correctly. Here is a variant that raises a warning at the start of the build instead of requiring an environment variable to be set.

Importing early also provides a good opportunity to check for version mismatches.

import traceback
from sphinx.util import logging
logger = logging.getLogger(__name__)
try:
    from osgeo import gdal
except ImportError as e:
    logger.warn("Failed to load GDAL Python bindings. The Python bindings must be accessible to build Python API documentation.")
    for line in traceback.format_exception(e):
        logger.info(line)
else:
    version_file = os.path.join(os.path.dirname(__file__), os.pardir, os.pardir, "VERSION")
    doc_version = open(version_file).read().strip()
    gdal.__version__

    if doc_version.strip() != gdal.__version__:
        logger.warn(f"Building documentation for GDAL {doc_version} but osgeo.gdal module has version {gdal.__version__}. Python API documentation may be incorrect.")

[rouault]

@dbaston Thanks for the suggestion. I've slightly updated it to work with Python < 3.10, and also support gdal.__version__ with a "dev" suffix