Part of epic #2345.
Goal
Add a user-guide page that explains how to use the GeoTIFF IO surface safely without reading source code or SUPPORTED_FEATURES directly.
Scope
Create docs/source/user_guide/geotiff_safe_io.rst and add it to docs/source/user_guide/index.rst.
Sections to cover:
- Which entry points to prefer (
open_geotiff, to_geotiff, dask variants) and what each one expects.
- How to read
SUPPORTED_FEATURES and the tier vocabulary (stable / advanced / experimental / internal-only).
- Recommended codec choices for the stable contract and what disqualifies a file from the stable subset.
- COG output: when to pass
cog=True, the layout it produces, and which combinations fall outside the stable contract.
- Fail-closed errors users will hit, what each one means, and how to opt in where an opt-in exists.
- Remote-read safety limits: env vars and parameters that govern byte budgets, range behavior, and private-host rejection.
- Pointers to the reference page and the release gate.
Out of scope
- Rewriting
attrs_contract.rst. Cross-link instead.
- Adding new code or new public APIs. This is documentation only.
Acceptance
- New
docs/source/user_guide/geotiff_safe_io.rst builds without warnings.
- It is referenced from
docs/source/user_guide/index.rst.
- It does not claim full GDAL / VRT / GPU parity anywhere.
- A user can answer "is this safe to rely on" from the page alone.
Part of epic #2345.
Goal
Add a user-guide page that explains how to use the GeoTIFF IO surface safely without reading source code or
SUPPORTED_FEATURESdirectly.Scope
Create
docs/source/user_guide/geotiff_safe_io.rstand add it todocs/source/user_guide/index.rst.Sections to cover:
open_geotiff,to_geotiff, dask variants) and what each one expects.SUPPORTED_FEATURESand the tier vocabulary (stable / advanced / experimental / internal-only).cog=True, the layout it produces, and which combinations fall outside the stable contract.Out of scope
attrs_contract.rst. Cross-link instead.Acceptance
docs/source/user_guide/geotiff_safe_io.rstbuilds without warnings.docs/source/user_guide/index.rst.