Doc: Add documentation for configuration options

[dbaston]

I used a throwaway script to look for configuration options that are read by CPLGetConfigOption but are not declared in the .rst documentation files. Some of these do not appear to be intended to be part of the public API (PG_USE_POSTGIS2_OPTIM), some may be superseded by open options/creation options, and others may simply be missing the .. config:: magic. Others could be added to driver pages or the global options page where appropriate.

The script:

import os
import re

rst_files = []
cpp_files = []

root_dir = '/home/dan/dev/gdal'

for root, dirs, files, in os.walk(root_dir, topdown=True):
    dirs[:] = [d for d in dirs if d != 'autotest']

    for file in files:
        if file.endswith('.rst'):
            rst_files.append(os.path.join(root, file))
        elif file.endswith('.cpp'):
            cpp_files.append(os.path.join(root, file))

rst_opts = set()

for file in rst_files:
    with open(file, 'rb') as rst:
        for line in rst:
            hit = re.search('config:: ([\\w]+)', line.decode(errors='replace'))
            if hit:
                rst_opts.add(hit[1])

cpp_opts = set()

for file in cpp_files:
    with open(file) as cpp:
        for line in cpp:
            hit = re.search('CPLGetConfigOption."([\\w]+)"', line)
            if hit:
                cpp_opts.add(hit[1])

undocumented = cpp_opts.difference(rst_opts)

for opt in sorted(undocumented):
    print(opt)

Current output:

ADRG_SIMULATE_MULTI_IMG
AMIGOCLOUD_MAX_CHUNK_SIZE
AWS_MAX_KEYS
AWS_ROLE_SESSION_NAME
AWS_STS_ENDPOINT
AWS_STS_REGION
AWS_TIMESTAMP
AZURE_CONFIG_DIR
AZURE_MAX_RESULTS
AZURE_SAS
BAG_GEOREF_MD_BLOCKXSIZE
BAG_GEOREF_MD_BLOCKYSIZE
BASISU_MAX_FILE_SIZE
BLACKLISTED_OPENCL_VENDOR
BLOCKXSIZE
BLOCKYSIZE
CARTODB_API_KEY
CARTODB_API_URL
CARTODB_HTTPS
CARTODB_MAX_CHUNK_SIZE
CHECK_DISK_FREE_SPACE
COG_TMP_COMPRESSION
COMPRESS_GEOM
CONVERT_YCBCR_TO_RGB
CPL_ALLOW_VSISTDIN
CPL_AWS_AUTODETECT_EC2
CPL_AWS_CHECK_HYPERVISOR_UUID
CPL_AWS_WEB_IDENTITY_ENABLE
CPL_AZURE_TIMESTAMP
CPL_AZURE_VM_API_ROOT_URL
CPL_CREATE_ZIP64
CPL_CURL_ENABLE_VSIMEM
CPL_CURL_IGNORE_ERROR
CPL_CURL_VERBOSE_DATA_IN
CPL_CURL_VSIMEM_PRINT_HEADERS
CPL_ENABLE_USERFAULTFD
CPL_ERROR_SEPARATOR
CPL_GCE_CHECK_LOCAL_FILES
CPL_GCE_CREDENTIALS_URL
CPL_GCE_SKIP
CPL_LOG_APPEND
CPL_MINIXML_RELAXED
CPL_OPENSSL_INIT_ENABLED
CPL_OSS_TIMESTAMP
CPL_RSA_SHA256_Sign
CPL_VSIGS_UNLINK_BATCH_SIZE
CPL_VSIL_CURL_ALLOWED_FILENAME
CPL_VSIL_CURL_MAX_RANGES
CPL_VSIL_CURL_SLOW_GET_SIZE
CPL_VSIL_GZIP_SAVE_INFO
CPL_VSIL_SHOW_NETWORK_STATS
CPL_VSIS3_LIST_UPLOADS_MAX
CPL_VSIS3_UNLINK_BATCH_SIZE
CPL_VSISTDIN_FILE
CPL_VSISTDIN_FILE_CLOSE
CPL_VSISTDIN_RESET_POSITION
CPL_ZIP_ENCODING
CREATE_GEOMETRY_COLUMNS
CREATE_METADATA_TABLES
CREATE_RASTER_TABLES
CREATE_TRIGGERS
DGN_LINK_FORMAT
DISABLE_OPEN_REAL_NETCDF_FILES
DRIVER_WISHED
DUMP_JP2_BOXES
DWG_ENCODING
DWG_MERGE_BLOCK_GEOMETRIES
DXF_HEADER_ONLY
DXF_MAX_BSPLINE_CONTROL_POINTS
ECW_AUTOGEN_J2I
ECW_CHECK_CORRECT_DECODING
ECW_CLEVER
ECW_DO_NOT_RESOLVE_DATUM_PROJECTION
ECW_ENCODE_COMPANY
ECW_ENCODE_KEY
ECW_LARGE_OK
ECW_OPTIMIZE_USE_NEAREST_NEIGHBOUR
EEDA_FORCE_BLOCK_SIZE
ES_ADD_PRETTY
ES_FORWARD_HTTP_HEADERS_FROM_ENV
FGDB_PER_LAYER_COPYING_TRANSACTION
FGDB_RESYNC_THRESHOLD
FGDB_SIMUL_FAIL
FGDB_SIMUL_FAIL_REOPEN
FGDB_STRING_WIDTH
FILEGDB_DISABLE_SPARSE_PAGES
FORCE_BLOCKSIZE
FUSIL_SRC_DIR
GDALCUTLINE_SKIP_CONTAINMENT_TEST
GDALWARP_DENSIFY_CUTLINE
GDALWARP_DUMP_WKT_TO_FILE
GDALWARP_IGNORE_BAD_CUTLINE
GDAL_ALLOW_LARGE_LIBJPEG_MEM_ALLOC
GDAL_ARRAY_OPEN_BY_FILENAME
GDAL_BAG_BLOCK_SIZE
GDAL_BAG_MAX_SIZE_VARRES_MAP
GDAL_BAG_MIN_OVR_SIZE
GDAL_CONFIG_FILE
GDAL_CURL_CA_BUNDLE
GDAL_DAAS_AUTHORIZATION
GDAL_DAAS_GET_BUFFER_URL
GDAL_DAAS_INITIAL_RETRY_DELAY
GDAL_DAAS_PERFORM_AUTH
GDAL_DAAS_SERVER_BYTE_LIMIT
GDAL_DEBUG_BLOCK_CACHE
GDAL_DEFAULT_CREATE_COPY
GDAL_DEFAULT_WMS_CACHE_PATH
GDAL_ECW_CACHE_MAXMEM
GDAL_ECW_WRITE_COMPANY
GDAL_ECW_WRITE_COMPRESSION_SOFTWARE
GDAL_ENABLE_PYTHON_PATH
GDAL_ENABLE_READ_WRITE_MUTEX
GDAL_ENABLE_WMS_CACHE
GDAL_GCPS_TO_GEOTRANSFORM_APPROX_OK
GDAL_GEOLOC_BACKMAP_OVERSAMPLE_FACTOR
GDAL_GEOLOC_INVERSE_METHOD
GDAL_GEOLOC_USE_MAX_ACCURACY
GDAL_GEOLOC_USE_TEMP_DATASETS
GDAL_GRID_POINT_COUNT_THRESHOLD
GDAL_GSSAPI_DELEGATION
GDAL_GTIFF_PREDICTOR_CHECKS
GDAL_HDF5_CHAR_AS_STRING
GDAL_HDF5_TEMP_ARRAY_ALLOC_SIZE
GDAL_HTTP_CONNECTTIMEOUT
GDAL_HTTP_COOKIE
GDAL_HTTP_COOKIEFILE
GDAL_HTTP_COOKIEJAR
GDAL_HTTP_ENABLE_ADVISE_READ
GDAL_HTTP_LOW_SPEED_LIMIT
GDAL_HTTP_LOW_SPEED_TIME
GDAL_HTTP_NETRC
GDAL_HTTP_NETRC_FILE
GDAL_HTTP_SSL_VERIFYSTATUS
GDAL_HTTP_USE_CAPI_STORE
GDAL_JP2K_ALT_OFFSETVECTOR_ORDER
GDAL_JPEG2000_STRUCTURE_MAX_LINES
GDAL_JPEGXL_MAX_BOX_BUFFER_SIZE
GDAL_LOCALE
GDAL_MAX_BAND_COUNT
GDAL_MAX_RAW_BLOCK_CACHE_SIZE
GDAL_NETCDF_CENTERLONG_180
GDAL_NO_COSTLY_OVERVIEW
GDAL_OGCAPI_TILEMATRIXSET_LIMITS
GDAL_ONE_BIG_READ
GDAL_OPENGIS_SCHEMAS
GDAL_OPEN_AFTER_COPY
GDAL_OVR_CHUNKYSIZE
GDAL_OVR_CHUNK_MAX_SIZE
GDAL_OVR_PROPAGATE_NODATA
GDAL_PDF_GEO_ENCODING
GDAL_PDF_LIMIT_PAGE_COUNT
GDAL_PDF_OGC_BP_READ_WKT
GDAL_PDF_OGC_BP_WRITE_WKT
GDAL_PDF_PRINT_COMMANDS
GDAL_PDF_USE_SPAWN
GDAL_PDF_WRITE_ESRI_CODE_AS_EPSG
GDAL_PDF_WRITE_GEOREF_ON_IMAGE
GDAL_PNG_SINGLE_BLOCK
GDAL_PNG_WHOLE_IMAGE_OPTIM
GDAL_PYTHON_DRIVER_PATH
GDAL_RASTERIO_RESAMPLING
GDAL_RB_FLUSHBLOCK_SLEEP_AFTER_RB_LOCK
GDAL_RB_LOCK_DEBUG_CONTENTION
GDAL_RB_LOCK_TYPE
GDAL_RB_TRYGET_SLEEP_AFTER_TAKE_LOCK
GDAL_READDIR_LIMIT_ON_OPEN
GDAL_REPORT_DIRTY_BLOCK_FLUSHING
GDAL_RPC_DEM_OPTIM
GDAL_SHARED_FILE
GDAL_TIFF_DEFLATE_SUBCODEC
GDAL_TIFF_ENDIANNESS
GDAL_USE_AVX
GDAL_USE_GEOJP2
GDAL_USE_GMLJP2
GDAL_USE_OPENCL
GDAL_USE_SSE
GDAL_USE_SSSE3
GDAL_VALIDATE_CREATION_OPTIONS
GDAL_VRT_PYTHON_EXCLUSIVE_LOCK
GDAL_WARP_USE_AFFINE_OPTIMIZATION
GDAL_WARP_USE_TRANSLATION_OPTIM
GDAL_WMS_MAX_CONNECTIONS
GDAL_ZARR_USE_OPTIMIZED_CODE_PATHS
GEOLOC_DUMP
GEOL_AS_GCPS
GEOR_FILTER_NODATA_VALUES
GEOR_INTERNAL_PYR
GMLAS_WARN_UNEXPECTED
GMLAS_XLINK_RAM_CACHE_SIZE
GMLAS_XML_MAX_CONTENT_SIZE
GMLAS_XML_MAX_LEVEL
GMLJP2OVERRIDE
GML_FETCH_ALL_GEOMETRIES
GML_HUGE_TEMPFILE
GML_REGISTRY
GML_REPORT_COMPD_CS
GML_SCHEMA_OUTPUT_NAME
GML_SKIP_CORRUPTED_FEATURES
GML_SRS_DIMENSION_IF_MISSING
GML_USE_OLD_FID_FORMAT
GMT_USE_TAB
GOA2_AUTH_URL_TOKEN
GOA2_CLIENT_ID
GOA2_CLIENT_SECRET
GOA2_EXPIRATION_DELAY
GOA2_NOW
GPKG_ADD_DEFINITION_12_063
GPKG_ALLOW_CRAZY_SETTINGS
GPKG_DEBUG
GPKG_FORCE_TEMPDB_COMPACTION
GPKG_NAME_CHECK
GPKG_NODATA
GPKG_PNG_SUPPORTS_2BANDS
GPKG_PNG_SUPPORTS_CT
GPKG_SIMUL_WEBP_3BAND
GRIB_CACHEMAX
GRIB_DEFAULT_SEMI_MAJOR
GRIB_DEFAULT_SEMI_MINOR
GRIB_PDS_ALL_BANDS
GRIB_USE_DEFAULT_SPHEROID
GRIB_WRITE_BITMAP_TEST
GTIFF_ALLOW_PREAD
GTIFF_ALPHA
GTIFF_DELETE_ON_ERROR
GTIFF_DONT_WRITE_BLOCKS
GTIFF_ESRI_CITATION
GTIFF_FORCE_RGBA
GTIFF_IMPLICIT_JPEG_OVR
GTIFF_IMPORT_FROM_EPSG
GTIFF_SRS_SOURCE
GTIFF_USE_DEFER_STRILE_LOADING
GTIFF_USE_MMAP
GTIFF_WRITE_IMAGE_STRUCTURE_METADATA
GXF_DATATYPE
HDF4_BLOCK_PIXELS
HDF5_SHIFT_GCPX_BY_180
HFA_USE_ESRI_PE_STRING
HFA_WRITE_PE_STRING
HOME
IDRISIDIR
ISG_SKIP_GEOREF_CONSISTENCY_CHECK
JP2KAK_BUFFERED
JP2KAK_MAX_BUFFER_SIZE
JP2KAK_PERSIST
JP2KAK_PRECISE
JP2KAK_USE_STRIPE_COMPRESSOR
JP2OPENJPEG_USE_THREADED_IO
JPEGMEM
JPEG_FORCE_INTERNAL_OVERVIEWS
JPEG_WRITE_MASK_BIT_ORDER
JPEG_WRITE_RGB
KML_DEBUG
KTX2_MAX_FILE_SIZE
KTX2_VERBOSE
L1B_FETCH_METADATA
L1B_HIGH_GCP_DENSITY
L1B_INTERPOL_GCPS
L1B_METADATA_DIRECTORY
LIBKML_ADD_RESOURCE_MAP
LIBKML_CAMERA_LATITUDE_FIELD
LIBKML_LAUNDER_FIELD_NAMES
LIBKML_STRICT_COMPLIANCE
MBTILES_PNG_SUPPORTS_2BANDS
MBTILES_PNG_SUPPORTS_CT
MDBDRIVER_PATH
MITAB_MAX_LINE_LENGTH
MRF_ALL_OVERVIEW_LEVELS
MRF_BYPASSCACHING
MSSQLSPATIAL_PWD
MSSQLSPATIAL_UID
MYSQL_TIMEOUT
NAS_GFS_TEMPLATE
NAS_INDICATOR
NAS_NO_RELATION_LAYER
NAS_SKIP_CORRUPTED_FEATURES
NETCDF_TMP_FILE
NITF_OPEN_UNDERLYING_DS
OCI_DEFAULT_DIM
ODBC_OGR_FID
ODS_RESOLVE_FORMULAS
OGR_API_SPY_FILE
OGR_API_SPY_SNAPSHOT_PATH
OGR_ARROW_READ_GDAL_FOOTER
OGR_ARROW_USE_VSI
OGR_ARROW_WRITE_GDAL_FOOTER
OGR_ARROW_WRITE_GEO
OGR_CSV_MAX_FIELD_COUNT
OGR_CSV_SIMULATE_VSISTDIN
OGR_CT_DEBUG
OGR_CT_FORCE_TRADITIONAL_GIS_ORDER
OGR_CT_OP_SELECTION
OGR_CT_PREFER_OFFICIAL_SRS_DEF
OGR_DEBUG_ORGANIZE_POLYGONS
OGR_DRIVER_PATH
OGR_EDIGEO_INCLUDE_FONT_FAMILY
OGR_EDIGEO_SORT_FOR_QGIS
OGR_EXPAT_UNLIMITED_MEM_ALLOC
OGR_FLATGEOBUF_STREAM_BASE_IMPL
OGR_GEOJSONSEQ_CHUNK_SIZE
OGR_GEOJSON_MAX_BYTES_FIRST_PASS
OGR_GEOJSON_MAX_FEATURES_FIRST_PASS
OGR_GEOJSON_REWRITE_IN_PLACE
OGR_GEOMETRY_ACCEPT_UNCLOSED_RING
OGR_GMLAS_XERCES_MAX_TIME
OGR_GML_NESTING_LEVEL
OGR_GPKG_ALLOW_THREADED_RTREE
OGR_GPKG_CHECK_SRS
OGR_GPKG_FOREIGN_KEY_CHECK
OGR_GPKG_GEOMCOLLECTION
OGR_GPKG_INTEGRITY_CHECK
OGR_GPKG_STREAM_BASE_IMPL
OGR_GPKG_USE_RTREE_FOR_GET_EXTENT
OGR_LVBAG_CHECK_ALL_FILES
OGR_LVBAG_MAX_OPENED
OGR_MONGODB_SPAT_INDEX_TYPE
OGR_MULTIPATCH_OMIT_Z
OGR_MVT_CLIP
OGR_MVT_REMOVE_TEMP_FILE
OGR_MVT_REUSE_TEMP_FILE
OGR_OAPIF_ALLOW_CQL_TEXT
OGR_ODS_MAX_FIELD_COUNT
OGR_PARQUET_BATCH_SIZE
OGR_PARQUET_GEO_METADATA
OGR_PARQUET_MAX_LISTED_FILES
OGR_PARQUET_MAX_NON_PARQUET_FILES
OGR_PARQUET_USE_METADATA_FILE
OGR_PARQUET_USE_STATISTICS
OGR_PARQUET_USE_VSI
OGR_PARQUET_WRITE_ARROW_EXTENSION_NAME
OGR_PARQUET_WRITE_ARROW_SCHEMA
OGR_PARQUET_WRITE_BBOX
OGR_PARQUET_WRITE_CRS
OGR_PARQUET_WRITE_GEO
OGR_PDF_SET_STYLE
OGR_PDS4_FIELD_DELIMITER
OGR_PG_DEBUG_GGT_CANCEL
OGR_PG_DEFERRED_CREATION
OGR_PG_JSON_TYPE
OGR_PG_STRING_TYPE
OGR_PG_UUID_TYPE
OGR_S57_OPTIONS
OGR_SETFIELD_NUMERIC_WARNING
OGR_SHAPE_ALLOW_NON_FINITE_COORDINATES
OGR_SHAPE_PACK_IN_PLACE
OGR_SHAPE_USE_VSIMEM_FOR_TEMP
OGR_SQLITE_ALLOW_EXTERNAL_ACCESS
OGR_SQLITE_DIALECT_USE_SPATIALITE
OGR_SQLITE_DISABLE_INSERT_TRIGGERS
OGR_SQLITE_ENABLE_DATETIME
OGR_SQLITE_EXACT_EXTENT
OGR_SQLITE_REGEXP
OGR_SQLITE_SPATIAL_FUNCTIONS
OGR_SQLITE_STATIC_VIRTUAL_OGR
OGR_SQLITE_VFS_MAXPATHNAME
OGR_SQL_STRICT
OGR_TABLE_LIMIT
OGR_VRT_FORCE_LOADING
OGR_VRT_MAX_OPENED
OGR_WFS3_API_URL
OGR_WFS_FIX_MAXFEATURES
OGR_WFS_LOAD_MULTIPLE_LAYER_DEFN
OGR_XERCES_TERMINATE
OPENCL_USE_CPU
OPENFILEGDB_CREATOR
OPENFILEGDB_DEFAULT_STRING_WIDTH
OPENFILEGDB_FORCE_SPX_DEPTH
OPENFILEGDB_GRID_SIZE
OPENFILEGDB_MAX_FEATURES_PER_SPX_PAGE
OPENFILEGDB_MODIFY_IN_PLACE
OPENFILEGDB_REPORT_DELETED_FEATURES
OPENFILEGDB_REPRODUCIBLE_UUID
OPENFILEGDB_SIMUL_WIN32
OPENFILEGDB_STRING_WIDTH
OPENFILEGDB_USE_INDEX
OPENFILEGDB_USE_SPATIAL_INDEX
OPENFILEGDB_WRITE_VCSWKID
OPENFILEGDB_WRITE_WKID
OSM_EXISTING_TMPFILE
OSM_INDEX_POINTS
OSM_INDEX_WAYS
OSM_MAX_INDEXED_KEYS
OSM_MAX_INDEXED_VALUES_PER_KEY
OSM_SQLITE_CACHE
OSM_UNLINK_TMPFILE
OSM_USE_POINTS_INDEX
OSM_USE_WAYS_INDEX
OSR_ADD_TOWGS84_ON_EXPORT_TO_PROJ4
OSR_ADD_TOWGS84_ON_EXPORT_TO_WKT1
OSR_ADD_TOWGS84_ON_IMPORT_FROM_EPSG
OSR_CT_USE_DEFAULT_EPSG_TOWGS84
OSR_DEFAULT_AXIS_MAPPING_STRATEGY
OSR_IMPORT_FROM_WKT_LIMIT
OSR_STRIP_TOWGS84
OSR_USE_APPROX_TMERC
OSR_USE_ETMERC
OSR_USE_NON_DEPRECATED
OSR_WKT_FORMAT
OZI_APPROX_GEOTRANSFORM
PARTIAL_TILES_JOURNAL_MODE
PDF_COORD_DOUBLE_PRECISION
PDF_DUMP_CATALOG
PDF_DUMP_OBJECT
PDF_DUMP_PARENT
PDF_DUMP_STREAM
PDF_REPORT_GCPS
PDF_USE_CTM
PDS4_ENDIANNESS
PDS4_FORCE_MASK
PDS4_SIGNEDNESS
PDS_LineProjOffset_Mult
PDS_LineProjOffset_Shift
PDS_SampleProjOffset_Mult
PDS_SampleProjOffset_Shift
PGCLIENTENCODING
PGHOST
PGPASSWORD
PGPORT
PGUSER
PG_COMMIT_WHEN_OVERWRITING
PG_DEFERRED_OVERVIEWS
PG_SKIP_VIEWS
PG_USE_GEOGRAPHY
PG_USE_POSTGIS
PG_USE_POSTGIS2_OPTIM
PL_CACHE_PATH
PL_URL
PREFERRED_OPENCL_VENDOR
PROJ_DATA
PROJ_LIB
PR_ALLOW_WHOLE_TABLE_SCAN
PR_DISABLE_GIST
PR_DISABLE_PK
PR_FORCE_LOAD_RASTERS
PR_NS_RES
PR_RESOLUTION_STRATEGY
PR_WE_RES
PST_INSTANCE
PST_OFFSET
QGIS_HACK
RAW_CHECK_FILE_SIZE
RAW_MEM_ALLOC_LIMIT_MB
RESTRICT_OUTPUT_DATASET_UPDATE
RL2_SHOW_ALL_PYRAMID_LEVELS
RMF_SET_VERTCS
RPC_INVERSE_LOG
RPC_INVERSE_VERBOSE
RPFTOC_FORCE_RGBA
RPFTOC_MAX_FRAME_COUNT
S57_CSV
S57_PROFILE
SENTINEL2_USE_MAIN_MTD
SPATIALITESO
SPATIALITE_LOAD
SQLITE_BUSY_TIMEOUT
SQLITE_USE_URI
SWIFT_MAX_KEYS
SXF_LAYER_FULLNAME
SXF_RSC_FILENAME
SXF_SET_VERTCS
TEMP
TIGER_LFIELD_AS_STRING
TIGER_VERSION
TILEDB_BINARY_TYPE
TILEDB_BUG
TILEDB_INT_TYPE
TILEDB_WKB_GEOMETRY_TYPE
TMPDIR
USER
USERNAME
USERPROFILE
USE_OSR_FIND_MATCHES
USE_SPILL
USE_SQLITE_DEBUG_MEMALLOC
USE_TILE_AS_BLOCK
VRT_ALLOW_MEM_DRIVER
VRT_MIN_MAX_FROM_SOURCES
VRT_SHARED_SOURCE
VSIAZ_CHUNK_SIZE
VSIAZ_CHUNK_SIZE_BYTES
VSICRYPT_ADD_KEY_CHECK
VSICRYPT_ALG
VSICRYPT_CRYPTO_RANDOM
VSICRYPT_DISPLAY_GENERATED_KEY
VSICRYPT_FREETEXT
VSICRYPT_IV
VSICRYPT_KEY
VSICRYPT_KEY_B64
VSICRYPT_MODE
VSICRYPT_SECTOR_SIZE
VSIS3_SIMULATE_THREADING
VSIS3_SYNC_MULTITHREADING
VSIWEBHDFS_SIZE
VSIWEBHDFS_SIZE_BYTES
VSI_FLUSH
WARP_THREAD_CHUNK_SIZE
WMS_INFO_FORMAT
ZARR_ALLOW_BIG_TILE_SIZE
ZMAP_PIXEL_IS_POINT
__chain_python_error_handlers

[dbaston]

Are the following reasonable indications of whether something should be documented?

• It appears in a non-code search result (GDAL_BAND_BLOCK_CACHE)
• It appears in NEWS (GDAL_OVR_PROPAGATE_NODATA)
• It appears in external code (GTIFF_FORCE_RGBA)
• It is part of a family of options, the others of which are documented (LIBKML_CAMERA_LATITUDE_FIELD, GDAL_HTTP_NETRC)

[rouault]

Are the following reasonable indications of whether something should be documented?

that seems reasonable. I would also add that if a config option is not tested in autotest/ and not documented, it might be a hint that either it shouldn't be documented, or a test should be written.

Some options mentioned in NEWS might have been added out of caution, to enable easy "revert", when a behaviour has been changed. In the good cases where the new behaviour works OK, the config option is actually not needed.

[dbaston]

I was thinking about whether it would be a good idea to add a check like this to the CI, but of course it would require some way to ignore options that are not considered public. Some ideas I had:

• maintain a text file list of "private" options
• add private options to the .rst files, with a :private: YES keyword or something to prevent them from being emitted
• add a CPLGetConfigOptionPrivate or something that would wrap CPLGetConfigOption but emit a warning like "Option XYZ is for development/testing purposes and may be removed without notice in a future release"
• do nothing!

[rouault]

I was thinking about whether it would be a good idea to add a check like this to the CI, but of course it would require some way to ignore options that are not considered public

Options 1 or 2 would seem fine to me. I feel less the CPLGetConfigOptionPrivate(), especially the warning part, since production code does call it. Or maybe you meant to emit the warning only if the option is defined?

[dbaston]

Or maybe you meant to emit the warning only if the option is defined?

Yes, that's what I meant.