Update pystac.utils docs (#735)

* Update pystac.utils docs

* Fix lint errors

* Add CHANGELOG entry for #735

* Add missing docs sections

* Fix duplicate object warnings when building docs

* Fix lint errors

* Replace hard-coded extension links with extlinks reference

* Suppress extlink warnings

* Fix lint error

* Ignore missing sphinx.util type stubs

CHANGELOG.md

@@ -8,6 +8,7 @@
 - Accept PathLike objects in `StacIO` I/O methods, `pystac.read_file` and `pystac.write_file` ([#728](https://github.com/stac-utils/pystac/pull/728))
 - Support for Storage Extension ([#745](https://github.com/stac-utils/pystac/pull/745))
 - Optional `StacIO` instance as argument to `Catalog.save`/`Catalog.normalize_and_save` ([#751](https://github.com/stac-utils/pystac/pull/751))
+- More thorough docstrings for `pystac.utils` functions and classes ([#735](https://github.com/stac-utils/pystac/pull/735))
 
 ### Removed
 

docs/api/serialization/identify.rst

@@ -5,3 +5,4 @@ pystac.serialization.identify
    :members:
    :undoc-members:
    :show-inheritance:
+   :noindex:

docs/api/utils.rst

@@ -4,4 +4,3 @@ pystac.utils
 .. automodule:: pystac.utils
     :members:
     :undoc-members:
-    :noindex:

docs/conf.py

@@ -17,6 +17,8 @@
 import subprocess
 from typing import Any, Dict, List
 
+from sphinx.util import logging
+
 sys.path.insert(0, os.path.abspath("."))
 sys.path.insert(0, os.path.abspath("../"))
 from pystac.version import __version__, STACVersion  # noqa:E402
@@ -231,8 +233,17 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
+    "dateutil": ("https://dateutil.readthedocs.io/en/stable", None),
 }
 
 # -- Substutition variables
 
 rst_epilog = f".. |stac_version| replace:: {STACVersion.DEFAULT_STAC_VERSION}"
+
+# -- Suppress warnings from the extlinks extension
+# We do this to avoid warnings like the following in our Jupyter notebook tutorials
+# where we do not want to use Sphinx constructs:
+# WARNING: hardcoded link 'https://github.com/stac-extensions/eo' could be replaced
+# by an extlink (try using ':stac-ext:`eo`' instead)
+linklogger = logging.getLogger("sphinx.ext.extlinks")
+linklogger.setLevel(40)  # Ignore messages less severe than ERROR

mypy.ini

@@ -7,3 +7,6 @@ ignore_missing_imports = True
 
 [mypy-setuptools.*]
 ignore_missing_imports = True
+
+[mypy-sphinx.util]
+ignore_missing_imports = True

pystac/extensions/datacube.py

@@ -1,7 +1,4 @@
-"""Implements the Datacube extension.
-
-https://github.com/stac-extensions/datacube
-"""
+"""Implements the :stac-ext:`Datacube Extension <datacube>`."""
 
 from abc import ABC
 from typing import Any, Dict, Generic, List, Optional, TypeVar, Union, cast

pystac/extensions/eo.py

@@ -1,7 +1,4 @@
-"""Implements the Electro-Optical (EO) extension.
-
-https://github.com/stac-extensions/eo
-"""
+"""Implements the :stac-ext:`Electro-Optical Extension <eo>`."""
 
 from typing import (
     Any,

pystac/extensions/file.py

@@ -1,7 +1,4 @@
-"""Implements the File extension.
-
-https://github.com/stac-extensions/file
-"""
+"""Implements the :stac-ext:`File Info Extension <file>`."""
 
 from typing import Any, Dict, Iterable, List, Optional, Union
 

pystac/extensions/item_assets.py

@@ -1,7 +1,4 @@
-"""Implements the Item Assets Definition extension.
-
-https://github.com/stac-extensions/item-assets
-"""
+"""Implements the :stac-ext:`Item Assets Definition Extension <item-assets>`."""
 
 from copy import deepcopy
 from typing import Any, Dict, List, Optional

pystac/extensions/label.py

@@ -1,7 +1,4 @@
-"""Implements the Label extension.
-
-https://github.com/stac-extensions/label
-"""
+"""Implements the :stac-ext:`Label Extension <label>`."""
 
 from pystac.extensions.base import ExtensionManagementMixin, SummariesExtension
 from typing import Any, Dict, Iterable, List, Optional, Sequence, Union, cast

pystac/extensions/pointcloud.py

@@ -1,7 +1,4 @@
-"""Implements the Point Cloud extension.
-
-https://github.com/stac-extensions/pointcloud
-"""
+"""Implements the :stac-ext:`Point Cloud Extension <pointcloud>`."""
 from typing import Any, Dict, Iterable, Generic, List, Optional, TypeVar, cast, Union
 
 import pystac

pystac/extensions/projection.py

@@ -1,7 +1,4 @@
-"""Implements the Projection extension.
-
-https://github.com/stac-extensions/projection
-"""
+"""Implements the :stac-ext:`Projection Extension <projection>`."""
 
 import json
 from typing import Any, Dict, Generic, Iterable, List, Optional, TypeVar, Union, cast

pystac/extensions/raster.py

@@ -1,7 +1,4 @@
-"""Implements the Raster extension.
-
-https://github.com/stac-extensions/raster
-"""
+"""Implements the :stac-ext:`Raster Extension <raster>`."""
 
 from typing import Any, Dict, Iterable, List, Optional, Union
 
@@ -373,8 +370,8 @@ def apply(
                 assumed to represent a sampling over the region of the pixel or a point
                 sample at the center of the pixel.
             data_type :The data type of the band.
-                One of the data types as described in
-                <https://github.com/stac-extensions/raster/#data-types>.
+                One of the data types as described in the
+                :stac-ext:`Raster Data Types <raster/#data-types> docs`.
             bits_per_sample : The actual number of bits used for this band.
                 Normally only present when the number of bits is non-standard for the
                 datatype, such as when a 1 bit TIFF is represented as byte
@@ -423,8 +420,8 @@ def create(
                 assumed to represent a sampling over the region of the pixel or a point
                 sample at the center of the pixel.
             data_type :The data type of the band.
-                One of the data types as described in
-                <https://github.com/stac-extensions/raster/#data-types>.
+                One of the data types as described in the
+                :stac-ext:`Raster Data Types <raster/#data-types> docs`.
             bits_per_sample : The actual number of bits used for this band.
                 Normally only present when the number of bits is non-standard for the
                 datatype, such as when a 1 bit TIFF is represented as byte

pystac/extensions/sar.py

@@ -1,7 +1,4 @@
-"""Implements the Synthetic-Aperture Radar (SAR) extension.
-
-https://github.com/stac-extensions/sar
-"""
+"""Implements the :stac-ext:`Synthetic-Aperture Radar (SAR) Extension <sar>`."""
 
 from typing import Any, Dict, Generic, Iterable, List, Optional, TypeVar, cast, Union
 

pystac/extensions/sat.py

@@ -1,7 +1,4 @@
-"""Implements the Satellite extension.
-
-https://github.com/stac-extensions/sat
-"""
+"""Implements the :stac-ext:`Satellite Extension <sat>`."""
 
 from datetime import datetime as Datetime
 from pystac.summaries import RangeSummary

pystac/extensions/scientific.py

@@ -1,6 +1,4 @@
-"""Implements the scientific extension.
-
-https://github.com/stac-extensions/scientific
+"""Implements the :stac-ext:`Scientific Citation Extension <scientific>`.
 
 For a description of Digital Object Identifiers (DOIs), see the DOI Handbook:
 

pystac/extensions/table.py

@@ -1,7 +1,4 @@
-"""Implements the Table extension
-
-https://github.com/stac-extensions/table
-"""
+"""Implements the :stac-ext:`Table Extension <table>.`"""
 from typing import Any, Dict, Generic, List, Optional, TypeVar, Union, cast
 
 import pystac

pystac/extensions/timestamps.py

@@ -1,7 +1,4 @@
-"""Implements the Timestamps extension.
-
-https://github.com/stac-extensions/timestamps
-"""
+"""Implements the :stac-ext:`Timestamps Extension <timestamps>`."""
 
 from datetime import datetime as datetime
 from pystac.summaries import RangeSummary

pystac/extensions/version.py

@@ -1,7 +1,4 @@
-"""Implements the Versioning Indicators extension.
-
-https://github.com/stac-extensions/version
-"""
+"""Implements the :stac-ext:`Versioning Indicators Extension <version>`."""
 from pystac.utils import get_required, map_opt
 from typing import Any, Dict, Generic, List, Optional, TypeVar, Union, cast
 
@@ -26,8 +23,8 @@
 class VersionRelType(StringEnum):
     """A list of rel types defined in the Version Extension.
 
-    See the `Version Extension Relation types
-    <https://github.com/stac-extensions/version#relation-types>`__ documentation
+    See the :stac-ext:`Version Extension Relation types
+    <version#relation-types>` documentation
     for details."""
 
     LATEST = "latest-version"

pystac/extensions/view.py

@@ -1,7 +1,4 @@
-"""Implement the View Geometry extension.
-
-https://github.com/stac-extensions/view
-"""
+"""Implement the :stac-ext:`View Geometry Extension <view>`."""
 
 from typing import Any, Dict, Generic, Iterable, Optional, TypeVar, Union, cast