Merge remote-tracking branch 'origin/feature/jd/1.0-refactors-doc-fix' into feature/rde/1.0-refactors

Author: lossyrob

README.md

@@ -114,6 +114,14 @@ To build and develop the documentation locally, make sure sphinx is available (w
 > make livehtml
 ```
 
+> Note: You will see some warnings along the lines of 
+> ```
+> WARNING: duplicate object description of pystac.Collection.id, 
+> other instance in api, use :noindex: for one of them
+> ``` 
+> for some of the
+> classes. This is expected due to [sphinx-doc/sphinx#8664](https://github.com/sphinx-doc/sphinx/issues/8664).
+
 Use 'make' without arguments to see a list of available commands.
 
 __Note__: `nbsphinx` requires that a local `pystac` is installed; use `pip install -e .`.

docs/api.rst

@@ -127,13 +127,6 @@ Link
    :members:
    :undoc-members:
 
-LinkType
-~~~~~~~~
-
-.. autoclass:: pystac.LinkType
-   :members:
-   :undoc-members:
-
 MediaType
 ~~~~~~~~~
 
@@ -149,7 +142,7 @@ STAC_IO
 
 STAC_IO is the utility mechanism that PySTAC uses for reading and writing. Users of PySTAC can hook into PySTAC by overriding members to utilize their own IO methods.
 
-.. autoclass:: pystac.STAC_IO
+.. autoclass:: pystac.stac_io.STAC_IO
    :members:
    :undoc-members:
 
@@ -193,17 +186,20 @@ ExtensionError
 Extensions
 ----------
 
-.. autoclass:: pystac.extensions.Extensions
-   :members:
-   :undoc-members:
+**TEMPORARILY REMOVED**
+.. .. autoclass:: pystac.extensions.Extensions
+..    :members:
+..    :undoc-members:
 
 ExtensionIndex
 ~~~~~~~~~~~~~~
 
-An ExtensionIndex is accessed through the :attr:`STACObject.ext <pystac.STACObject.ext>` property and is the primary way to access information and functionality around STAC extensions.
+**TEMPORARILY REMOVED**
+
+.. An ExtensionIndex is accessed through the :attr:`STACObject.ext <pystac.STACObject.ext>` property and is the primary way to access information and functionality around STAC extensions.
 
-.. autoclass:: pystac.stac_object.ExtensionIndex
-   :members: __getitem__, __getattr__, enable, implements
+.. .. autoclass:: pystac.stac_object.ExtensionIndex
+..    :members: __getitem__, __getattr__, enable, implements
 
 
 EO Extension
@@ -214,17 +210,21 @@ These classes are representations of the `EO Extension Spec <https://github.com/
 EOItemExt
 ~~~~~~~~~
 
-.. autoclass:: pystac.extensions.eo.EOItemExt
-   :members:
-   :undoc-members:
-   :show-inheritance:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.eo.EOItemExt
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
 
 Band
 ~~~~
 
-.. autoclass:: pystac.extensions.eo.Band
-   :members:
-   :undoc-members:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.eo.Band
+..    :members:
+..    :undoc-members:
 
 
 Label Extension
@@ -235,10 +235,12 @@ These classes are representations of the `Label Extension Spec <https://github.c
 LabelItemExt
 ~~~~~~~~~~~~
 
-.. autoclass:: pystac.extensions.label.LabelItemExt
-   :members:
-   :undoc-members:
-   :show-inheritance:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.label.LabelItemExt
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
 
 LabelType
 ~~~~~~~~~
@@ -283,10 +285,12 @@ Implements the `Point Cloud Extension <https://github.com/radiantearth/stac-spec
 PointcloudItemExt
 ~~~~~~~~~~~~~~~~~
 
-.. autoclass:: pystac.extensions.pointcloud.PointcloudItemExt
-   :members:
-   :undoc-members:
-   :show-inheritance:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.pointcloud.PointcloudItemExt
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
 
 Projection Extension
 --------------------
@@ -296,10 +300,12 @@ Implements the `Projection Extension <https://github.com/radiantearth/stac-spec/
 ProjectionItemExt
 ~~~~~~~~~~~~~~~~~
 
-.. autoclass:: pystac.extensions.projection.ProjectionItemExt
-   :members:
-   :undoc-members:
-   :show-inheritance:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.projection.ProjectionItemExt
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
 
 Timestamps Extension
 --------------------
@@ -309,10 +315,12 @@ Implements the `Timestamps Extension <https://github.com/radiantearth/stac-spec/
 TimestampsItemExt
 ~~~~~~~~~~~~~~~~~
 
-.. autoclass:: pystac.extensions.timestamps.TimestampsItemExt
-   :members:
-   :undoc-members:
-   :show-inheritance:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.timestamps.TimestampsItemExt
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
 
 SAR Extension
 -------------
@@ -322,10 +330,12 @@ Implements the `SAR Extension <https://github.com/radiantearth/stac-spec/tree/v1
 SarItemExt
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: pystac.extensions.sar.SarItemExt
-   :members:
-   :undoc-members:
-   :show-inheritance:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.sar.SarItemExt
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
 
 SAT Extension
 -------------
@@ -335,25 +345,31 @@ Implements the `SAT Extension <https://github.com/radiantearth/stac-spec/tree/v1
 SatItemExt
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: pystac.extensions.sar.SatItemExt
-   :members:
-   :undoc-members:
-   :show-inheritance:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.sar.SatItemExt
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
 
 Single File STAC Extension
 --------------------------
 
 These classes are representations of the `Single File STAC Extension <https://github.com/radiantearth/stac-spec/tree/v1.0.0-beta.2/extensions/single-file-stac>`_.
 
-.. automodule:: pystac.extensions.single_file_stac
-   :members: create_single_file_stac
+**TEMPORARILY REMOVED**
+
+.. .. automodule:: pystac.extensions.single_file_stac
+..    :members: create_single_file_stac
 
 SingleFileSTACCatalogExt
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: pystac.extensions.single_file_stac.SingleFileSTACCatalogExt
-   :members:
-   :undoc-members:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.single_file_stac.SingleFileSTACCatalogExt
+..    :members:
+..    :undoc-members:
 
 Version Extension
 -----------------
@@ -363,18 +379,22 @@ Implements the `Version Extension <https://github.com/radiantearth/stac-spec/tre
 VersionCollectionExt
 ~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: pystac.extensions.version.VersionCollectionExt
-   :members:
-   :undoc-members:
-   :show-inheritance:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.version.VersionCollectionExt
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
 
 VersionItemExt
 ~~~~~~~~~~~~~~
 
-.. autoclass:: pystac.extensions.version.VersionItemExt
-   :members:
-   :undoc-members:
-   :show-inheritance:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.version.VersionItemExt
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
 
 View Geometry Extension
 -----------------------
@@ -384,10 +404,12 @@ Implements the `View Geometry Extension <https://github.com/radiantearth/stac-sp
 ViewItemExt
 ~~~~~~~~~~~
 
-.. autoclass:: pystac.extensions.view.ViewItemExt
-   :members:
-   :undoc-members:
-   :show-inheritance:
+**TEMPORARILY REMOVED**
+
+.. .. autoclass:: pystac.extensions.view.ViewItemExt
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
 
 Serialization
 -------------
@@ -401,17 +423,17 @@ Identification
 .. automodule:: pystac.serialization
    :members: identify_stac_object
 
-.. autoclass:: pystac.serialization.STACJSONDescription
-   :members:
-   :undoc-members:
+.. .. autoclass:: pystac.serialization.STACJSONDescription
+..    :members:
+..    :undoc-members:
 
 .. autoclass:: pystac.serialization.STACVersionRange
    :members:
    :undoc-members:
 
-.. autoclass:: pystac.serialization.STACVersionID
-   :members:
-   :undoc-members:
+.. .. autoclass:: pystac.serialization.STACVersionID
+..    :members:
+..    :undoc-members:
 
 
 Migration
@@ -456,8 +478,8 @@ schema URIs. A default implementation is included that uses known locations; how
 can provide their own schema URI maps in a :class:`~pystac.validation.JsonSchemaSTACValidator`
 to modify the URIs used.
 
-.. autoclass:: pystac.validation.SchemaUriMap
-   :members:
+.. .. autoclass:: pystac.validation.SchemaUriMap
+..    :members:
 
 .. autoclass:: pystac.validation.schema_uri_map.DefaultSchemaUriMap
    :members:

docs/concepts.rst

@@ -159,7 +159,7 @@ are relative to the linking object's file location. For example, if a catalog at
 then that link should resolve to the absolute path ``/some/location/item-id/item-id.json``.
 
 Links are set as absolute or relative HREFs at save time, as determine by the root catalog's catalog_type
-:attribute:`~pystac.Catalog.catalog_type`. This means that, even if the stored HREF of the link is absolute,
+:attr:`~pystac.Catalog.catalog_type`. This means that, even if the stored HREF of the link is absolute,
 if the root ``catalog_type=CatalogType.RELATIVE_PUBLISHED`` or ``catalog_type=CatalogType.SELF_CONTAINED``
 and subsequent serializing of the any links in the catalog will produce a relative link,
 based on the self link of the parent object.
@@ -396,7 +396,7 @@ Item Asset properties
 
 Properties that apply to Items can be found in two places: the Item's properties or in any of an Item's Assets. If the property is on an Asset, it applies only that specific asset. For example, gsd defined for an Item represents the best Ground Sample Distance (resolution) for the data within the Item. However, some assets may be lower resolution and thus have a higher gsd. In that case, the `gsd` can be found on the Asset.
 
-See the STAC documentation on `Additional Fields for Assets <https://github.com/radiantearth/stac-spec/blob/v1.0.0-beta.2/item-spec/item-spec.md#additional-fields-for-assets>`_ and the relevant `Best Practices <https://github.com/radiantearth/stac-spec/blob/v1.0.0-beta.2/best-practices.md#common-use-cases-of-additional-fields-for-assets>`_ for more information.
+See the STAC documentation on `Additional Fields for Assets <https://github.com/radiantearth/stac-spec/blob/v1.0.0-beta.2/item-spec/item-spec.md#additional-fields-for-assets>`_ and the relevant `Best Practices <https://github.com/radiantearth/stac-spec/blob/v1.0.0-beta.2/best-practices.md#common-use-cases-of-additional-fields-for-assets>`__ for more information.
 
 The implementation of this feature in PySTAC uses the method described here and is consistent across Item and ItemExtensions. The bare property names represent values for the Item only, but for each property where it is possible to set on both the Item or the Asset there is a ``get_`` and ``set_`` methods that optionally take an Asset. For the ``get_`` methods, if the property is found on the Asset, the Asset's value is used; otherwise the Item's value will be used. For the ``set_`` method, if an Asset is passed in the value will be applied to the Asset and not the Item.
 

pystac/catalog.py

@@ -221,7 +221,7 @@ def add_child(
         self.add_link(Link.child(child, title=title))
 
     def add_children(self, children: Iterable["Catalog"]) -> None:
-        """Adds links to multiple :class:`~pystac.Catalog` or `~pystac.Collection`s.
+        """Adds links to multiple :class:`~pystac.Catalog` or `~pystac.Collection`\s.
         This method will set each child's parent to this object, and their root to
         this Catalog's root.
 

pystac/stac_io.py

@@ -286,7 +286,7 @@ def read_text(cls, uri: str) -> str:
 
         Note:
             This method uses the :func:`STAC_IO.read_text_method
-            <pystac.STAC_IO.read_text_method>`. If you want to modify the behavior of
+            <STAC_IO.read_text_method>`. If you want to modify the behavior of
             STAC_IO in order to enable additional URI types, replace that member
             with your own implementation.
         """
@@ -302,7 +302,7 @@ def write_text(cls, uri: str, txt: str) -> None:
 
         Note:
             This method uses the :func:`STAC_IO.write_text_method
-            <pystac.STAC_IO.write_text_method>`. If you want to modify the behavior of
+            <STAC_IO.write_text_method>`. If you want to modify the behavior of
             STAC_IO in order to enable additional URI types, replace that member
             with your own implementation.
         """
@@ -321,7 +321,7 @@ def read_json(cls, uri: str) -> Dict[str, Any]:
 
         Note:
             This method uses the :func:`STAC_IO.read_text_method
-            <pystac.STAC_IO.read_text_method>`. If you want to modify the behavior of
+            <STAC_IO.read_text_method>`. If you want to modify the behavior of
             STAC_IO in order to enable additional URI types, replace that member
             with your own implementation.
         """
@@ -345,7 +345,7 @@ def read_stac_object(
 
         Note:
             This method uses the :func:`STAC_IO.read_text_method
-            <pystac.STAC_IO.read_text_method>`. If you want to modify the behavior of
+            <STAC_IO.read_text_method>`. If you want to modify the behavior of
             STAC_IO in order to enable additional URI types, replace that member
             with your own implementation.
         """
@@ -362,7 +362,7 @@ def save_json(cls, uri: str, json_dict: Dict[str, Any]) -> None:
 
         Note:
             This method uses the :func:`STAC_IO.write_text_method
-            <pystac.STAC_IO.write_text_method>`. If you want to modify the behavior of
+            <STAC_IO.write_text_method>`. If you want to modify the behavior of
             STAC_IO in order to enable additional URI types, replace that member
             with your own implementation.
         """

requirements-dev.txt

@@ -6,10 +6,9 @@ codespell==1.17.1
 ipython==7.16.1
 jsonschema==3.2.0
 pylint==1.9.1
-Sphinx==1.8.0
+Sphinx==3.5.4
 sphinx-autobuild==0.7.1
 sphinxcontrib-fulltoc==1.2.0
-sphinxcontrib-napoleon==0.7
 nbsphinx==0.7.1
 coverage==5.2.*