Add docs and hint about extension summaries

[jsignell]

Related Issue(s):

• closes Add documentation around adding projection/raster extension to collection for summaries/item assets #890

Description:

I added some docs to the concepts page of the docs and I also added a hint in the exception that is raised when ext is called with an invalid object type.

from pystac import Collection, Extent, SpatialExtent, TemporalExtent
from pystac.extensions.projection import ProjectionExtension

collection = Collection(
    "an-id",
    "a description",
    Extent(
        SpatialExtent([-106.0, 41.0, -105.0, 42.0]),
        TemporalExtent.from_now(),
    ),
)
ProjectionExtension.ext(collection, add_if_missing=True)

---------------------------------------------------------------------------
ExtensionTypeError                        Traceback (most recent call last)
Cell In[1], line 12
      2 from pystac.extensions.projection import ProjectionExtension
      4 collection = Collection(
      5     "an-id",
      6     "a description",
   (...)
     10     ),
     11 )
---> 12 ProjectionExtension.ext(collection, add_if_missing=True)

File ~/pystac/pystac/extensions/projection.py:289, in ProjectionExtension.ext(cls, obj, add_if_missing)
    287     return cast(ProjectionExtension[T], AssetProjectionExtension(obj))
    288 else:
--> 289     raise pystac.ExtensionTypeError(cls._ext_error_message(obj))

ExtensionTypeError: ProjectionExtension does not apply to type 'Collection'. Hint: Did you mean to use `.summaries` instead?

PR Checklist:

• pre-commit hooks pass locally
• Tests pass (run scripts/test)
• Documentation has been updated to reflect changes, if applicable
• This PR maintains or improves overall codebase code coverage.
• Changes are added to the CHANGELOG. See the docs for information about adding to the changelog.

[codecov]

Codecov Report

Patch coverage: 92.00% and no project coverage change.

Comparison is base (9e86cda) 91.18% compared to head (820bc7f) 91.19%.

❗ Current head 820bc7f differs from pull request most recent head 961b4c7. Consider uploading reports for the commit 961b4c7 to get more accurate results

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1157   +/-   ##
=======================================
  Coverage   91.18%   91.19%           
=======================================
  Files          49       49           
  Lines        6635     6641    +6     
  Branches      980      981    +1     
=======================================
+ Hits         6050     6056    +6     
  Misses        410      410           
  Partials      175      175           

Impacted Files	Coverage Δ
pystac/extensions/classification.py	95.60% <0.00%> (ø)
pystac/extensions/mgrs.py	96.05% <0.00%> (ø)
pystac/extensions/base.py	94.44% <100.00%> (+0.50%)	⬆️
pystac/extensions/datacube.py	66.46% <100.00%> (ø)
pystac/extensions/eo.py	93.92% <100.00%> (ø)
pystac/extensions/file.py	91.79% <100.00%> (ø)
pystac/extensions/grid.py	100.00% <100.00%> (ø)
pystac/extensions/item_assets.py	95.37% <100.00%> (ø)
pystac/extensions/label.py	93.83% <100.00%> (ø)
pystac/extensions/pointcloud.py	97.81% <100.00%> (ø)
... and 10 more

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[ircwaves]

Excellent dry-out. Code-cov seems happy, but notes that mgrs and classification don't test the refactored error handling (nor did they before).