Update pystac.utils docs

[duckontheweb]

Related Issue(s):

• Closes Document utils methods #249

Description:

Updates docstrings with references to internal and external API docs and adds more detail to some of the docstrings.

PR Checklist:

• Code is formatted (run pre-commit run --all-files)
• 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-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.54%. Comparing base (ccf12d2) to head (c6492f1).
⚠️ Report is 709 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #735   +/-   ##
=======================================
  Coverage   94.54%   94.54%           
=======================================
  Files          79       79           
  Lines       11606    11606           
  Branches     1370     1370           
=======================================
  Hits        10973    10973           
  Misses        455      455           
  Partials      178      178           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gadomski]

I got two batches of warnings when building locally, wanted to see if they were worth fixing with this PR. First:

/Users/gadomski/Code/pystac/pystac/extensions/datacube.py:docstring of pystac.extensions.datacube:3: WARNING: hardcoded link 'https://github.com/stac-extensions/datacube' could be replaced by an extlink (try using ':stac-ext:`datacube`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/eo.py:docstring of pystac.extensions.eo:3: WARNING: hardcoded link 'https://github.com/stac-extensions/eo' could be replaced by an extlink (try using ':stac-ext:`eo`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/file.py:docstring of pystac.extensions.file:3: WARNING: hardcoded link 'https://github.com/stac-extensions/file' could be replaced by an extlink (try using ':stac-ext:`file`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/item_assets.py:docstring of pystac.extensions.item_assets:3: WARNING: hardcoded link 'https://github.com/stac-extensions/item-assets' could be replaced by an extlink (try using ':stac-ext:`item-assets`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/label.py:docstring of pystac.extensions.label:3: WARNING: hardcoded link 'https://github.com/stac-extensions/label' could be replaced by an extlink (try using ':stac-ext:`label`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/pointcloud.py:docstring of pystac.extensions.pointcloud:3: WARNING: hardcoded link 'https://github.com/stac-extensions/pointcloud' could be replaced by an extlink (try using ':stac-ext:`pointcloud`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/projection.py:docstring of pystac.extensions.projection:3: WARNING: hardcoded link 'https://github.com/stac-extensions/projection' could be replaced by an extlink (try using ':stac-ext:`projection`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/raster.py:docstring of pystac.extensions.raster:3: WARNING: hardcoded link 'https://github.com/stac-extensions/raster' could be replaced by an extlink (try using ':stac-ext:`raster`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/raster.py:docstring of pystac.extensions.raster.RasterBand.apply:: WARNING: hardcoded link 'https://github.com/stac-extensions/raster/#data-types' could be replaced by an extlink (try using ':stac-ext:`raster/#data-types`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/raster.py:docstring of pystac.extensions.raster.RasterBand.create:: WARNING: hardcoded link 'https://github.com/stac-extensions/raster/#data-types' could be replaced by an extlink (try using ':stac-ext:`raster/#data-types`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/sar.py:docstring of pystac.extensions.sar:3: WARNING: hardcoded link 'https://github.com/stac-extensions/sar' could be replaced by an extlink (try using ':stac-ext:`sar`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/sat.py:docstring of pystac.extensions.sat:3: WARNING: hardcoded link 'https://github.com/stac-extensions/sat' could be replaced by an extlink (try using ':stac-ext:`sat`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/scientific.py:docstring of pystac.extensions.scientific:3: WARNING: hardcoded link 'https://github.com/stac-extensions/scientific' could be replaced by an extlink (try using ':stac-ext:`scientific`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/table.py:docstring of pystac.extensions.table:3: WARNING: hardcoded link 'https://github.com/stac-extensions/table' could be replaced by an extlink (try using ':stac-ext:`table`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/timestamps.py:docstring of pystac.extensions.timestamps:3: WARNING: hardcoded link 'https://github.com/stac-extensions/timestamps' could be replaced by an extlink (try using ':stac-ext:`timestamps`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/version.py:docstring of pystac.extensions.version:3: WARNING: hardcoded link 'https://github.com/stac-extensions/version' could be replaced by an extlink (try using ':stac-ext:`version`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/version.py:docstring of pystac.extensions.version.VersionRelType:3: WARNING: hardcoded link 'https://github.com/stac-extensions/version#relation-types' could be replaced by an extlink (try using ':stac-ext:`version#relation-types`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/view.py:docstring of pystac.extensions.view:3: WARNING: hardcoded link 'https://github.com/stac-extensions/view' could be replaced by an extlink (try using ':stac-ext:`view`' instead)
/Users/gadomski/Code/pystac/docs/quickstart.ipynb:736: WARNING: hardcoded link 'https://github.com/stac-extensions/eo' could be replaced by an extlink (try using ':stac-ext:`eo`' instead)
/Users/gadomski/Code/pystac/docs/quickstart.ipynb:736: WARNING: hardcoded link 'https://github.com/stac-extensions/view' could be replaced by an extlink (try using ':stac-ext:`view`' instead)
/Users/gadomski/Code/pystac/docs/quickstart.ipynb:736: WARNING: hardcoded link 'https://github.com/stac-extensions/projection' could be replaced by an extlink (try using ':stac-ext:`projection`' instead)
/Users/gadomski/Code/pystac/docs/quickstart.ipynb:817: WARNING: hardcoded link 'https://github.com/stac-extensions/eo#item-properties-or-asset-fields' could be replaced by an extlink (try using ':stac-ext:`eo#item-properties-or-asset-fields`' instead)

Second:

/Users/gadomski/Code/pystac/pystac/serialization/identify.py:docstring of pystac.serialization.identify.STACJSONDescription.extensions:1: WARNING: duplicate object description of pystac.serialization.identify.STACJSONDescription.extensions, other instance in api/serialization/identify, use :noindex: for one of them
/Users/gadomski/Code/pystac/pystac/serialization/identify.py:docstring of pystac.serialization.identify.STACJSONDescription.object_type:1: WARNING: duplicate object description of pystac.serialization.identify.STACJSONDescription.object_type, other instance in api/serialization/identify, use :noindex: for one of them
/Users/gadomski/Code/pystac/pystac/serialization/identify.py:docstring of pystac.serialization.identify.STACJSONDescription.version_range:1: WARNING: duplicate object description of pystac.serialization.identify.STACJSONDescription.version_range, other instance in api/serialization/identify, use :noindex: for one of them

I also have a couple of inline comments re: quick fixups.

[duckontheweb]

I got two batches of warnings when building locally, wanted to see if they were worth fixing with this PR. First:

/Users/gadomski/Code/pystac/pystac/extensions/datacube.py:docstring of pystac.extensions.datacube:3: WARNING: hardcoded link 'https://github.com/stac-extensions/datacube' could be replaced by an extlink (try using ':stac-ext:`datacube`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/eo.py:docstring of pystac.extensions.eo:3: WARNING: hardcoded link 'https://github.com/stac-extensions/eo' could be replaced by an extlink (try using ':stac-ext:`eo`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/file.py:docstring of pystac.extensions.file:3: WARNING: hardcoded link 'https://github.com/stac-extensions/file' could be replaced by an extlink (try using ':stac-ext:`file`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/item_assets.py:docstring of pystac.extensions.item_assets:3: WARNING: hardcoded link 'https://github.com/stac-extensions/item-assets' could be replaced by an extlink (try using ':stac-ext:`item-assets`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/label.py:docstring of pystac.extensions.label:3: WARNING: hardcoded link 'https://github.com/stac-extensions/label' could be replaced by an extlink (try using ':stac-ext:`label`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/pointcloud.py:docstring of pystac.extensions.pointcloud:3: WARNING: hardcoded link 'https://github.com/stac-extensions/pointcloud' could be replaced by an extlink (try using ':stac-ext:`pointcloud`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/projection.py:docstring of pystac.extensions.projection:3: WARNING: hardcoded link 'https://github.com/stac-extensions/projection' could be replaced by an extlink (try using ':stac-ext:`projection`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/raster.py:docstring of pystac.extensions.raster:3: WARNING: hardcoded link 'https://github.com/stac-extensions/raster' could be replaced by an extlink (try using ':stac-ext:`raster`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/raster.py:docstring of pystac.extensions.raster.RasterBand.apply:: WARNING: hardcoded link 'https://github.com/stac-extensions/raster/#data-types' could be replaced by an extlink (try using ':stac-ext:`raster/#data-types`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/raster.py:docstring of pystac.extensions.raster.RasterBand.create:: WARNING: hardcoded link 'https://github.com/stac-extensions/raster/#data-types' could be replaced by an extlink (try using ':stac-ext:`raster/#data-types`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/sar.py:docstring of pystac.extensions.sar:3: WARNING: hardcoded link 'https://github.com/stac-extensions/sar' could be replaced by an extlink (try using ':stac-ext:`sar`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/sat.py:docstring of pystac.extensions.sat:3: WARNING: hardcoded link 'https://github.com/stac-extensions/sat' could be replaced by an extlink (try using ':stac-ext:`sat`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/scientific.py:docstring of pystac.extensions.scientific:3: WARNING: hardcoded link 'https://github.com/stac-extensions/scientific' could be replaced by an extlink (try using ':stac-ext:`scientific`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/table.py:docstring of pystac.extensions.table:3: WARNING: hardcoded link 'https://github.com/stac-extensions/table' could be replaced by an extlink (try using ':stac-ext:`table`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/timestamps.py:docstring of pystac.extensions.timestamps:3: WARNING: hardcoded link 'https://github.com/stac-extensions/timestamps' could be replaced by an extlink (try using ':stac-ext:`timestamps`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/version.py:docstring of pystac.extensions.version:3: WARNING: hardcoded link 'https://github.com/stac-extensions/version' could be replaced by an extlink (try using ':stac-ext:`version`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/version.py:docstring of pystac.extensions.version.VersionRelType:3: WARNING: hardcoded link 'https://github.com/stac-extensions/version#relation-types' could be replaced by an extlink (try using ':stac-ext:`version#relation-types`' instead)
/Users/gadomski/Code/pystac/pystac/extensions/view.py:docstring of pystac.extensions.view:3: WARNING: hardcoded link 'https://github.com/stac-extensions/view' could be replaced by an extlink (try using ':stac-ext:`view`' instead)
/Users/gadomski/Code/pystac/docs/quickstart.ipynb:736: WARNING: hardcoded link 'https://github.com/stac-extensions/eo' could be replaced by an extlink (try using ':stac-ext:`eo`' instead)
/Users/gadomski/Code/pystac/docs/quickstart.ipynb:736: WARNING: hardcoded link 'https://github.com/stac-extensions/view' could be replaced by an extlink (try using ':stac-ext:`view`' instead)
/Users/gadomski/Code/pystac/docs/quickstart.ipynb:736: WARNING: hardcoded link 'https://github.com/stac-extensions/projection' could be replaced by an extlink (try using ':stac-ext:`projection`' instead)
/Users/gadomski/Code/pystac/docs/quickstart.ipynb:817: WARNING: hardcoded link 'https://github.com/stac-extensions/eo#item-properties-or-asset-fields' could be replaced by an extlink (try using ':stac-ext:`eo#item-properties-or-asset-fields`' instead)

This first batch of warnings was due to our use of hard-coded links in a lot of the extension modules (e.g. here) and in some of our tutorial notebooks. 6fc5008 replaces the hard-coded links in the source code with :stac-ext: extlink references. The links in the tutorial notebooks are a little trickier because we provide direct links to these notebooks in our docs (see the "GitHub Version" links to the tutorials here), so the :stac-ext: reference won't render properly as a link in those notebooks. Using Markdown syntax for the links results in the same warnings (see sphinx-doc/sphinx#10012(comment)).
I suppressed these warnings from the extlink extension in c39e43b, but I'm not sure if that's really the best approach since it suppresses all warnings coming out of that extension. We could also live with the remaining warnings for now until sphinx-doc/sphinx#10012 is resolved, I'm fine with either approach.

Second:

/Users/gadomski/Code/pystac/pystac/serialization/identify.py:docstring of pystac.serialization.identify.STACJSONDescription.extensions:1: WARNING: duplicate object description of pystac.serialization.identify.STACJSONDescription.extensions, other instance in api/serialization/identify, use :noindex: for one of them
/Users/gadomski/Code/pystac/pystac/serialization/identify.py:docstring of pystac.serialization.identify.STACJSONDescription.object_type:1: WARNING: duplicate object description of pystac.serialization.identify.STACJSONDescription.object_type, other instance in api/serialization/identify, use :noindex: for one of them
/Users/gadomski/Code/pystac/pystac/serialization/identify.py:docstring of pystac.serialization.identify.STACJSONDescription.version_range:1: WARNING: duplicate object description of pystac.serialization.identify.STACJSONDescription.version_range, other instance in api/serialization/identify, use :noindex: for one of them

I also have a couple of inline comments re: quick fixups.

This batch of warnings is fixed by 3d75e7a

[duckontheweb]

I had to configure mypy to ignore missing sphinx.util type stubs to satisfy the CI even though I was unable to reproduce this issue locally.