From 2d175d11223738778b54dfd37451134b0c291d44 Mon Sep 17 00:00:00 2001
From: Jon Duckworth <duckontheweb@gmail.com>
Date: Wed, 23 Feb 2022 12:34:00 -0500
Subject: [PATCH] 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                        |   1 +
 docs/api/serialization/identify.rst |   1 +
 docs/api/utils.rst                  |   1 -
 docs/conf.py                        |  11 ++
 mypy.ini                            |   3 +
 pystac/extensions/datacube.py       |   5 +-
 pystac/extensions/eo.py             |   5 +-
 pystac/extensions/file.py           |   5 +-
 pystac/extensions/item_assets.py    |   5 +-
 pystac/extensions/label.py          |   5 +-
 pystac/extensions/pointcloud.py     |   5 +-
 pystac/extensions/projection.py     |   5 +-
 pystac/extensions/raster.py         |  13 +-
 pystac/extensions/sar.py            |   5 +-
 pystac/extensions/sat.py            |   5 +-
 pystac/extensions/scientific.py     |   4 +-
 pystac/extensions/table.py          |   5 +-
 pystac/extensions/timestamps.py     |   5 +-
 pystac/extensions/version.py        |   9 +-
 pystac/extensions/view.py           |   5 +-
 pystac/utils.py                     | 181 ++++++++++++++++++++++------
 21 files changed, 180 insertions(+), 104 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fb65031da..b52675631 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/docs/api/serialization/identify.rst b/docs/api/serialization/identify.rst
index adbff0a9e..97451bf51 100644
--- a/docs/api/serialization/identify.rst
+++ b/docs/api/serialization/identify.rst
@@ -5,3 +5,4 @@ pystac.serialization.identify
    :members:
    :undoc-members:
    :show-inheritance:
+   :noindex:
diff --git a/docs/api/utils.rst b/docs/api/utils.rst
index 4ce4f8d35..7417438ee 100644
--- a/docs/api/utils.rst
+++ b/docs/api/utils.rst
@@ -4,4 +4,3 @@ pystac.utils
 .. automodule:: pystac.utils
     :members:
     :undoc-members:
-    :noindex:
diff --git a/docs/conf.py b/docs/conf.py
index 3bdd208e8..4c7a93382 100644
--- a/docs/conf.py
+++ b/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
diff --git a/mypy.ini b/mypy.ini
index 2ad047526..ffdd91a23 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -7,3 +7,6 @@ ignore_missing_imports = True
 
 [mypy-setuptools.*]
 ignore_missing_imports = True
+
+[mypy-sphinx.util]
+ignore_missing_imports = True
diff --git a/pystac/extensions/datacube.py b/pystac/extensions/datacube.py
index 2758b2d4e..d02264a64 100644
--- a/pystac/extensions/datacube.py
+++ b/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
diff --git a/pystac/extensions/eo.py b/pystac/extensions/eo.py
index 3ad48c96f..12699eaf7 100644
--- a/pystac/extensions/eo.py
+++ b/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,
diff --git a/pystac/extensions/file.py b/pystac/extensions/file.py
index 02d8b428b..63840cfd7 100644
--- a/pystac/extensions/file.py
+++ b/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
 
diff --git a/pystac/extensions/item_assets.py b/pystac/extensions/item_assets.py
index a37197e23..c92b1282f 100644
--- a/pystac/extensions/item_assets.py
+++ b/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
diff --git a/pystac/extensions/label.py b/pystac/extensions/label.py
index 6c2e043db..d5dfb9b28 100644
--- a/pystac/extensions/label.py
+++ b/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
diff --git a/pystac/extensions/pointcloud.py b/pystac/extensions/pointcloud.py
index 9917253af..83bdd7e59 100644
--- a/pystac/extensions/pointcloud.py
+++ b/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
diff --git a/pystac/extensions/projection.py b/pystac/extensions/projection.py
index ba90adbe3..7c9568347 100644
--- a/pystac/extensions/projection.py
+++ b/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
diff --git a/pystac/extensions/raster.py b/pystac/extensions/raster.py
index 2b1b2c2fa..6119b61e7 100644
--- a/pystac/extensions/raster.py
+++ b/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
diff --git a/pystac/extensions/sar.py b/pystac/extensions/sar.py
index 02ec3496a..47fbf2ce8 100644
--- a/pystac/extensions/sar.py
+++ b/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
 
diff --git a/pystac/extensions/sat.py b/pystac/extensions/sat.py
index b89a9f562..5b33cc5f2 100644
--- a/pystac/extensions/sat.py
+++ b/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
diff --git a/pystac/extensions/scientific.py b/pystac/extensions/scientific.py
index c4f6ab485..6bc163aa5 100644
--- a/pystac/extensions/scientific.py
+++ b/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:
 
diff --git a/pystac/extensions/table.py b/pystac/extensions/table.py
index 06571cfb9..bab1198d6 100644
--- a/pystac/extensions/table.py
+++ b/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
diff --git a/pystac/extensions/timestamps.py b/pystac/extensions/timestamps.py
index f8adc89ea..d5c89f0fb 100644
--- a/pystac/extensions/timestamps.py
+++ b/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
diff --git a/pystac/extensions/version.py b/pystac/extensions/version.py
index 1d846e359..ba4e3063e 100644
--- a/pystac/extensions/version.py
+++ b/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"
diff --git a/pystac/extensions/view.py b/pystac/extensions/view.py
index 9b9bc08f6..123e9e453 100644
--- a/pystac/extensions/view.py
+++ b/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
 
diff --git a/pystac/utils.py b/pystac/utils.py
index f79493db8..8c1d4fd04 100644
--- a/pystac/utils.py
+++ b/pystac/utils.py
@@ -13,10 +13,18 @@
 
 
 def safe_urlparse(href: str) -> URLParseResult:
-    """Version of URL parse that takes into account windows paths.
+    """Wrapper around :func:`urllib.parse.urlparse` that returns consistent results for
+    both Windows and UNIX file paths.
 
-    A windows absolute path will be parsed with a scheme from urllib.parse.urlparse.
-    This method will take this into account.
+    For Windows paths, this function will include the drive prefix (e.g. ``"D:\\"``) as
+    part of the ``path`` of the :class:`urllib.parse.ParseResult` rather than as the
+    ``scheme`` for consistency with handling of UNIX/LINUX file paths.
+
+    Args:
+        href (str) : The HREF to parse. May be a local file path or URL.
+
+    Returns:
+        urllib.parse.ParseResult : The named tuple representing the parsed HREF.
     """
     parsed = urlparse(href)
     if parsed.scheme != "" and href.lower().startswith("{}:\\".format(parsed.scheme)):
@@ -38,19 +46,28 @@ def safe_urlparse(href: str) -> URLParseResult:
 
 
 class StringEnum(str, Enum):
-    """Base Enum class for string enums that will serialize as the string value."""
+    """Base :class:`enum.Enum` class for string enums that will serialize as the string
+    value."""
 
     def __str__(self) -> str:
         return cast(str, self.value)
 
 
 class JoinType(StringEnum):
-    """Allowed join types for the :func:`_join` function."""
+    """Allowed join types for :func:`~pystac.utils.join_path_or_url`."""
 
     @staticmethod
     def from_parsed_uri(parsed_uri: URLParseResult) -> "JoinType":
         """Determines the appropriate join type based on the scheme of the parsed
-        result."""
+        result.
+
+        Args:
+            parsed_uri (urllib.parse.ParseResult) : A named tuple representing the
+                parsed URI.
+
+        Returns:
+            JoinType : The join type for the URI.
+        """
         if parsed_uri.scheme == "":
             return JoinType.PATH
         else:
@@ -61,8 +78,19 @@ def from_parsed_uri(parsed_uri: URLParseResult) -> "JoinType":
 
 
 def join_path_or_url(join_type: JoinType, *args: str) -> str:
-    """Version of os.path.join that takes into account whether or not we are working
-    with a URL."""
+    """Functions similarly to :func:`os.path.join`, but can be used to join either a
+    local file path or a URL.
+
+    Args:
+        join_type (JoinType) : One of ``JoinType.PATH`` or ``JoinType.URL``. If
+            ``JoinType.PATH``, then :func:`os.path.join` is used for the join.
+            If ``JoinType.URL``, then :func:`posixpath.join` is used.
+        *args (str): Additional positional string arguments to be joined.
+
+    Returns:
+        str : The joined path
+
+    """
 
     if join_type == JoinType.PATH:
         return _pathlib.join(*args)
@@ -127,19 +155,21 @@ def _make_relative_href_path(
 def make_relative_href(
     source_href: str, start_href: str, start_is_dir: bool = False
 ) -> str:
-    """Makes a given HREF relative to the given starting HREF.
+    """Returns a new string that represents the ``source_href`` as a path relative to
+    ``start_href``. If ``source_href`` and ``start_href`` do not share a common parent,
+    then ``source_href`` is returned unchanged.
+
+    May be used on either local file paths or URLs.
 
     Args:
         source_href : The HREF to make relative.
-        start_href : The HREF that the resulting HREF will be relative with
-            respect to.
-        start_is_dir : If True, the start_href is treated as a directory.
-            Otherwise, the start_href is considered to be a file HREF.
-            Defaults to False.
+        start_href : The HREF that the resulting HREF will be relative to.
+        start_is_dir : If ``True``, ``start_href`` is treated as a directory.
+            Otherwise, ``start_href`` is considered to be a path to a file. Defaults to
+            ``False``.
 
     Returns:
-        str: The relative HREF. If the source_href and start_href do not share a common
-        parent, then source_href will be returned unchanged.
+        str: The relative HREF.
     """
 
     parsed_source = safe_urlparse(source_href)
@@ -219,20 +249,24 @@ def _make_absolute_href_path(
 def make_absolute_href(
     source_href: str, start_href: Optional[str] = None, start_is_dir: bool = False
 ) -> str:
-    """Makes a given HREF absolute based on the given starting HREF.
+    """Returns a new string that represents ``source_href`` as an absolute path. If
+    ``source_href`` is already absolute it is returned unchanged. If ``source_href``
+    is relative, the absolute HREF is constructed by joining ``source_href`` to
+    ``start_href``.
+
+    May be used on either local file paths or URLs.
 
     Args:
         source_href : The HREF to make absolute.
-        start_href : The HREF that will be used as the basis for which to resolve
-            relative paths, if source_href is a relative path. Defaults to the
-            current working directory.
-        start_is_dir : If True, the start_href is treated as a directory.
-            Otherwise, the start_href is considered to be a file HREF.
-            Defaults to False.
+        start_href : The HREF that will be used as the basis for resolving relative
+            paths, if ``source_href`` is a relative path. Defaults to the current
+            working directory.
+        start_is_dir : If ``True``, ``start_href`` is treated as a directory.
+            Otherwise, ``start_href`` is considered to be a path to a file. Defaults to
+            ``False``.
 
     Returns:
-        str: The absolute HREF. If the source_href is already an absolute href,
-        then it will be returned unchanged.
+        str: The absolute HREF.
     """
     if start_href is None:
         start_href = os.getcwd()
@@ -253,24 +287,29 @@ def make_absolute_href(
 def is_absolute_href(href: str) -> bool:
     """Determines if an HREF is absolute or not.
 
+    May be used on either local file paths or URLs.
+
     Args:
         href : The HREF to consider.
 
     Returns:
-        bool: True if the given HREF is absolute, False if it is relative.
+        bool: ``True`` if the given HREF is absolute, ``False`` if it is relative.
     """
     parsed = safe_urlparse(href)
     return parsed.scheme != "" or _pathlib.isabs(parsed.path)
 
 
 def datetime_to_str(dt: datetime) -> str:
-    """Convert a python datetime to an ISO8601 string
+    """Converts a :class:`datetime.datetime` instance to an ISO8601 string in the
+    `RFC 3339, section 5.6
+    <https://datatracker.ietf.org/doc/html/rfc3339#section-5.6>`__ format required by
+    the :stac-spec:`STAC Spec <master/item-spec/common-metadata.md#date-and-time>`.
 
     Args:
         dt : The datetime to convert.
 
     Returns:
-        str: The ISO8601 formatted string representing the datetime.
+        str: The ISO8601 (RFC 3339) formatted string representing the datetime.
     """
     if dt.tzinfo is None:
         dt = dt.replace(tzinfo=timezone.utc)
@@ -284,6 +323,13 @@ def datetime_to_str(dt: datetime) -> str:
 
 
 def str_to_datetime(s: str) -> datetime:
+    """Converts a string timestamp to a :class:`datetime.datetime` instance using
+    :meth:`dateutil.parser.parse` under the hood. The input string may be in any
+    format :std:doc:`supported by the parser <parser>`.
+
+    Args:
+        s (str) : The string to convert to :class:`datetime.datetime`.
+    """
     return dateutil.parser.parse(s)
 
 
@@ -337,23 +383,68 @@ def extract_coords(coords: List[Union[List[float], List[List[Any]]]]) -> None:
 
 
 def map_opt(fn: Callable[[T], U], v: Optional[T]) -> Optional[U]:
-    """Maps the value of an option to another value, returning
-    None if the input option is None.
+    """Maps the value of an optional type to another value, returning
+    ``None`` if the input option is ``None``.
+
+    Args:
+        fn (Callable) : A function that maps the non-optional value of type ``T`` to
+            another value. This function will be called on non-``None`` values of
+            ``v``.
+        v (Optional[T]) : The optional value to map.
+
+    Examples:
+
+        Given an optional value like the following...
+
+        .. code-block:: python
+
+            maybe_item: Optional[pystac.Item] = ...
+
+        ...you could replace...
+
+        .. code-block:: python
+
+            maybe_item_id: Optional[str] = None
+            if maybe_item is not None:
+                maybe_item_id = maybe_item.id
+
+        ...with:
+
+        .. code-block:: python
+
+            maybe_item_id = map_opt(lambda item: item.id, maybe_item)
     """
     return v if v is None else fn(v)
 
 
 def get_opt(option: Optional[T]) -> T:
-    """Retrieves the value of the Optional type.
+    """Retrieves the value of the ``Optional`` type, raising a :exc:`ValueError` if
+    the value is ``None``.
 
-    If the Optional is None, this will raise a value error.
     Use this to get a properly typed value from an optional
-    in contexts where you can be certain the value is not None.
-    If there is potential for a non-None value, it's best to handle
-    the None case of the optional instead of using this method.
+    in contexts where you can be certain the value is not ``None``.
+    If there is potential for a non-``None`` value, it's best to handle
+    the ``None`` case of the optional instead of using this method.
+
+    Args:
+        option (Optional[T]) : Some ``Optional`` value
 
     Returns:
         The value of type T wrapped by the Optional[T]
+
+    Examples:
+
+        .. code-block:: python
+
+            d = {
+                "some_key": "some_value"
+            }
+
+            # This passes
+            val: str = get_opt(d.get("some_key"))
+
+            # This raises a ValueError
+            val: str = get_opt(d.get("does_not_exist"))
     """
     if option is None:
         raise ValueError("Cannot get value from None")
@@ -361,9 +452,23 @@ def get_opt(option: Optional[T]) -> T:
 
 
 def get_required(option: Optional[T], obj: Union[str, Any], prop: str) -> T:
-    """Retrieves an optional value that comes from a required property.
-    If the option is None, throws an RequiredPropertyError with
-    the given obj and property
+    """Retrieves an ``Optional`` value that comes from a required property of some
+    object. If the option is ``None``, throws an :exc:`pystac.RequiredPropertyMissing`
+    with the given obj and property.
+
+    This method is primarily used internally to retrieve properly typed required
+    properties from dictionaries. For an example usage, see the
+    :attr:`pystac.extensions.eo.Band.name` source code.
+
+    Args:
+        option (Optional[T]) : The ``Optional`` value.
+        obj (str, Any) : The object from which the value is being retrieved. This will
+            be passed to the :exc:`~pystac.RequiredPropertyMissing` exception if
+            ``option`` is ``None``.
+        prop (str) : The name of the property being retrieved.
+
+    Returns:
+        T : The properly typed, non-``None`` value.
     """
     if option is None:
         raise RequiredPropertyMissing(obj, prop)