geotiff: sync attrs_contract.rst with the deprecated-tier landings#2015
Merged
Conversation
The four PR 7 deprecation slices (#2010 vertical, #2011 geographic, #2013 projected, #2014 colormap variants) moved 13 attrs from the pass-through tier to a new deprecated tier in ``xrspatial/geotiff/_attrs.py`` but did not update the user-guide page, which left ``docs/source/user_guide/attrs_contract.rst`` listing those attrs as round-trip-best-effort while the Python code fires a DeprecationWarning every time one is emitted. This is docs-only: * Trim ``Pass-through keys`` table to ``image_description``, ``extra_samples``, ``colormap`` -- the three attrs that genuinely round-trip via ``_merge_friendly_extra_tags``. The 11 GeoKey- derived attrs plus the two colormap variants moved out. * Merge the two separate deprecated sections that existed pre-PR (``Deprecated keys`` for colormap variants, ``Deprecated GeoKey attrs`` for the GeoKey slices) into one ``Deprecated keys`` section with two subsections: GeoKey-derived attrs (with the shared pyproj migration recipe) and matplotlib colormap variants (with per-row migration in a list-table). * Update the page's opening summary from "three tiers" to "four tiers" so the first paragraph matches the table-of-contents. * Update the ``Round-trip invariants`` section: the pass-through subsection now reflects that only three attrs live there and all three round-trip; add a deprecated subsection that explains the warning-only phase and points at the future contract-version bump to 2 when removal lands. No production-code change. Verified the file still parses with docutils (Sphinx-specific ``:func:`` / ``:mod:`` role warnings are the same pattern used across the rest of the docs). Refs #1984.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs-only follow-up. The four PR 7 deprecation slices (#2010 vertical, #2011 geographic, #2013 projected, #2014 colormap variants) moved 13 attrs from the pass-through tier to a new deprecated tier in the Python module docstring of
xrspatial/geotiff/_attrs.py, but did not update the user-guide page. As a resultdocs/source/user_guide/attrs_contract.rststill listed those 13 attrs as round-trip-best-effort while the code fires aDeprecationWarningevery time one is emitted on read.This PR brings the user-guide page back in line with the code:
Pass-through keystable toimage_description,extra_samples,colormap(the three attrs that actually round-trip via_merge_friendly_extra_tags). The eleven GeoKey-derived attrs plus the two colormap variants moved out.Deprecated keysfor the colormap variants,Deprecated GeoKey attrsfor the GeoKey slices) into oneDeprecated keyssection with two subsections: GeoKey-derived attrs (sharing the pyproj migration recipe) and matplotlib colormap variants (per-row migration in a list-table).Round-trip invariantssection: the pass-through subsection now reflects that only three attrs live there and all three round-trip; add a deprecated subsection that explains the warning-only phase and points at the future contract-version bump to2.No production-code change.
Test plan
docutilsparses the page (:func:/:mod:role warnings are Sphinx-only; same pattern as the rest of the docs).Refs #1984.