Publish the VRT support contract (#2327)

[brendancol]

Closes #2327. Parent: #2321 (GeoTIFF release hardening, sub-PR 1 of 6).

Summary

Docs-only. Lock down the supported VRT subset so readers can tell which VRTs the reader expects to handle and which it is allowed to reject.

• docs/source/reference/geotiff.rst: new "VRT support matrix" section. Calls out the supported subset (simple GDAL VRT mosaics over GeoTIFF sources; compatible CRS, transform orientation, pixel size, dtype, and band count; windowed and dask reads over the same subset; explicit nodata with mixed-band rejection by default; missing_sources='raise' as the default), the explicit non-goals (warped VRTs, arbitrary resampling, mixed metadata without an opt-in, nested VRTs, complex / mask / alpha bands, full GDAL parity), plus one safe-usage example and one intentionally-raises example.
• xrspatial/geotiff/__init__.py (open_geotiff for .vrt paths), xrspatial/geotiff/_backends/vrt.py (read_vrt), xrspatial/geotiff/_writers/vrt.py (write_vrt): docstrings echo the same subset / non-goals summary and carry the two examples.

VRT was already at the advanced tier in SUPPORTED_FEATURES (reader.vrt); no change there.

Backend coverage

No code paths touched. Existing VRT tests (eager numpy, dask, GPU where applicable) keep passing. Tier text in each docstring is unchanged.

Test plan

• pytest xrspatial/geotiff/tests/ -k vrt — 665 passed, 27 skipped on local environment.
• pytest xrspatial/geotiff/tests/test_signature_parity_1631.py xrspatial/geotiff/tests/test_to_geotiff_bigtiff_doc_1683.py — 9 passed (docstring / signature parity gates).
• RST round-trip parse of docs/source/reference/geotiff.rst via docutils.
• CI: full geotiff suite green.

[brendancol]

PR Review: Publish the VRT support contract (#2334)

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

• xrspatial/geotiff/_backends/vrt.py:169-191: the new Examples block sits before the Parameters / Returns / Notes sections. numpydoc puts Examples after those sections, and that's the order you used in open_geotiff and write_vrt in this same PR (xrspatial/geotiff/__init__.py:536, xrspatial/geotiff/_writers/vrt.py:95). Sphinx will render either order, but the three sibling docstrings disagreeing on section order is the bit worth fixing. Move the Examples block to sit below Notes so all three agree.

Nits (optional improvements)

• docs/source/reference/geotiff.rst:241-242: the "Intentionally raises" snippet imports open_geotiff and MixedBandMetadataError on two separate from xrspatial.geotiff import ... lines. One combined import line is a touch tighter.
• xrspatial/geotiff/_writers/vrt.py:101-103: the safe-usage example uses source_files=['tile_west.tif', 'tile_east.tif']. The # doctest: +SKIP keeps doctest from running the example against absent files, so it's fine. A one-line comment saying the paths are illustrative would help on first read.

What looks good

• Docs-only, narrowly scoped, four touched files agree on the contract text.
• VRT tier text in read_vrt / write_vrt is unchanged; both still say Tier: Advanced (issue #2137). SUPPORTED_FEATURES['reader.vrt'] was already 'advanced', so the "mark as advanced wherever tiers are described" acceptance is met without rewording the tier label.
• The example imports resolve. xrspatial.geotiff.MixedBandMetadataError is exported via __init__.py __all__ (verified locally).
• All doctest blocks carry # doctest: +SKIP, so a future pytest doctest run will not try to execute them against absent files.
• Existing VRT tests (665 passed, 27 skipped) and the docstring / signature parity gates (test_signature_parity_1631.py, test_to_geotiff_bigtiff_doc_1683.py) still pass.

Checklist

• Algorithm correctness (N/A; docs only)
• Backend parity (N/A; no code paths touched)
• NaN handling (N/A)
• Edge-case tests (N/A; docs only)
• Dask chunk boundaries (N/A)
• No premature materialization or unnecessary copies (N/A)
• Benchmark (not needed; docs only)
• README feature matrix updated (skipped per rockout brief; no backend coverage change)
• Docstrings present and accurate (the point of the PR)

[brendancol]

Follow-up review (post-suggestion fixes)

Re-checked the PR after 7c34495b:

• Suggestion (numpydoc section order on read_vrt): fixed. Examples block now sits below Notes; read_vrt / open_geotiff / write_vrt agree on order.
• Nit (combined import in the "Intentionally raises" RST snippet): fixed.
• Nit (illustrative-paths note on write_vrt example): fixed.

No new findings. Existing VRT tests (665 passed, 27 skipped) and the docstring / signature parity gates (test_signature_parity_1631.py, test_to_geotiff_bigtiff_doc_1683.py) still pass.