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 `.""" 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 `.""" 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 `.""" 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 `.""" 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