Updates and fixes to README, index, quickstart, and usage (#792)

* Updates and fixes to README, index, quickstart, and usage

* remove incorrect link in pr template

* Update docs/index.rst

Co-authored-by: Julia Signell <[email protected]>

* revert install instructions

* User ORNL CLOUD for collections search

* revert usage

---------

Co-authored-by: Julia Signell <[email protected]>

Author: philvarner

.github/pull_request_template.md

@@ -10,4 +10,4 @@
 
 - [ ] Code is formatted
 - [ ] Tests pass
-- [ ] Changes are added to the [CHANGELOG](https://github.com/stac-utils/pystac-api-client/blob/main/CHANGELOG.md)
+- [ ] Changes are added to CHANGELOG.md

README.md

@@ -10,8 +10,12 @@ A Python client for working with [STAC](https://stacspec.org/) APIs.
 
 ## Installation
 
-Install from PyPi.
-Other than [PySTAC](https://pystac.readthedocs.io) itself, the only dependencies for **pystac-client** are the Python [requests](https://docs.python-requests.org) and [dateutil](https://dateutil.readthedocs.io) libraries.
+PySTAC Client is published to PyPi as [pystac-client](https://pypi.org/project/pystac-client/).
+
+The only direct Python dependencies of **pystac-client** are [PySTAC](https://pystac.readthedocs.io),
+[requests](https://docs.python-requests.org), and [dateutil](https://dateutil.readthedocs.io).
+
+To install with pip, run:
 
 ```shell
 python -m pip install pystac-client

docs/index.rst

@@ -1,17 +1,10 @@
-.. pystac-client documentation master file, created by
-   sphinx-quickstart on Sat Feb 27 14:27:12 2021.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 PySTAC Client Documentation
 ===========================
 
-The STAC Python Client (``pystac_client``) is a Python package for working with STAC
-Catalogs and APIs that conform to the
-`STAC <https://github.com/radiantearth/stac-spec>`__ and
-`STAC API <https://github.com/radiantearth/stac-api-spec>`__ specs in a seamless way.
+PySTAC Client is a Python package for working with `STAC <https://github.com/radiantearth/stac-spec>`__
+Catalogs and `STAC APIs <https://github.com/radiantearth/stac-api-spec>`__.
 PySTAC Client builds upon PySTAC through higher-level functionality and ability to
-leverage STAC API search endpoints.
+access STAC API search endpoints.
 
 STAC Versions
 =============
@@ -20,7 +13,7 @@ STAC Versions
 | pystac-client | STAC spec | STAC API Spec               |
 +===============+===========+=============================+
 | 0.8.x         | 1.0.x     | 1.0.0-beta.1 - 1.0.0        |
-+ --------------+-----------+-----------------------------+
++---------------+-----------+-----------------------------+
 | 0.7.x         | 1.0.x     | 1.0.0-beta.1 - 1.0.0        |
 +---------------+-----------+-----------------------------+
 | 0.6.x         | 1.0.x     | 1.0.0-beta.1 - 1.0.0-rc.2   |
@@ -37,13 +30,15 @@ STAC Versions
 Installation
 ------------
 
-.. code-block:: console
+``pystac-client`` requires `Python >=3.10 <https://www.python.org/>`__.
 
-   $ pip install pystac-client
+To install with pip, run:
+
+.. code-block:: console
 
-``pystac_client`` requires `Python >=3.8 <https://www.python.org/>`__.
+   $ python -m pip install pystac-client
 
-This will install the dependencies :doc:`PySTAC <pystac:index>`,
+This will install the dependencies :doc:`pystac <pystac:index>`,
 :doc:`python-dateutil <dateutil:index>`, and :doc:`requests <requests:index>`.
 
 Acknowledgements

docs/quickstart.rst

@@ -1,13 +1,13 @@
 Quickstart
 ----------
 
-pystac-client can be used as either a Command Line Interface (CLI) or a
+PySTAC Client can be used as either a Command Line Interface (CLI) or a
 Python library.
 
 CLI
 ~~~
 
-Use the CLI to quickly make item- or collection-level searches and
+Use the CLI to quickly perform Item or Collection searches and
 output or save the results.
 
 The ``--matched`` switch performs a search with limit=1 so does not get
@@ -108,7 +108,7 @@ a spatial extent that intersects Scandinavia.
     43 items matched
 
 Since most STAC APIs have not yet implemented the `collection search 
-extension <https://github.com/stac-api-extensions/collection-search>`_, 
+extension <https://github.com/stac-api-extensions/collection-search>`__, 
 ``pystac-client`` will perform a limited client-side 
 filter on the full list of collections using only the ``bbox``, 
 ``datetime``, and ``q`` (free-text search) parameters.
@@ -120,49 +120,60 @@ applied client-side.
 Python
 ~~~~~~
 
-To use the Python library, first a Client instance is created for a
-specific STAC API (use the root URL):
+First, create a Client instance configured to use a specific STAC API by the root URL of that API. For this example, we
+will use `Earth Search <https://earth-search.aws.element84.com/v1>`__.
 
 .. code-block:: python
 
     from pystac_client import Client
 
     client = Client.open("https://earth-search.aws.element84.com/v1")
 
-Create an item-level search:
+Create an Item Search instance that represents a search to run. This does not actually run a search yet --
+that does not happen until a method is called that requires data from the STAC API.
 
 .. code-block:: python
 
     search = client.search(
         max_items=10,
-        collections=['sentinel-2-l2a'],
+        collections=["sentinel-2-c1-l2a"],
         bbox=[-72.5,40.5,-72,41]
     )
+
+Calling ``matched()`` will send a request to the STAC API and retrieve a single item and metadata about how many Items
+match the search criteria.
+
+.. code-block:: python
+
     print(f"{search.matched()} items found")
 
-The ``items()`` iterator method can be used to iterate through all resulting items.
+The ``items()`` iterator method can be used to iterate through all resulting items. This iterator
+hides the pagination behavior that the may occur if there are sufficient results. Be careful with this
+method -- you could end up iterating over the entire catalog if ``max_items`` is not set!
 
 .. code-block:: python
 
     for item in search.items():
         print(item.id)
 
-Use `item_collection()` to convert all Items from a search into a single `PySTAC
+Use ``item_collection()`` to convert all Items from a search into a single `PySTAC
 ItemCollection <https://pystac.readthedocs.io/en/latest/api/pystac.html#pystac.ItemCollection>`__.
-The ``ItemCollection`` can then be saved as a GeoJSON FeatureCollection.
+The ``ItemCollection`` can then be saved as a GeoJSON FeatureCollection. This requires retrieving all
+of the results from the search, so it may take some time to retrieve all the paginated responses.
 
 .. code-block:: python
 
     item_collection = search.item_collection()
-    item_collection.save_object('my_itemcollection.json')
-
+    item_collection.save_object("my_itemcollection.json")
 
-Create a collection-level search:
+Some STAC APIs also implement the Collection Search Extension. Earth Search does not, so we use the
+ORNL_CLOUD CMR-STAC Catalog instead:
 
 .. code-block:: python
 
+    client = Client.open("https://cmr.earthdata.nasa.gov/stac/ORNL_CLOUD")
     collection_search = client.collection_search(
-        q='"sentinel-2" OR "sentinel-1"',
+        q="rain",
     )
     print(f"{collection_search.matched()} collections found")
 

pystac_client/collection_search.py

@@ -372,7 +372,6 @@ def matched(self) -> int | None:
             count = len(page["collections"])
 
             for page in iter:
-                print(f"found {len(page['collections'])} on the next page")
                 count += len(page["collections"])
 
             found = count