Merge pull request #106 from stac-utils/docs

more docs updates

Author: matthewhanson

.readthedocs.yml

@@ -15,10 +15,5 @@ formats:
   - pdf
   - htmlzip
 
-# Optionally set the version of Python and requirements required to build your docs
-python:
-  version: 3.8
-  install:
-    - method: pip
-      path: .
-    - requirements: requirements-docs.txt
+conda:
+  environment: docs/environment.yml

docs/conf.py

@@ -61,6 +61,8 @@
     )
 }
 
+nbsphinx_allow_errors = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/environment.yml

@@ -0,0 +1,9 @@
+name: pystac-client-docs
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.8
+  - pip:
+    - -r ../requirements-docs.txt
+    - -e ../

docs/quickstart.rst

@@ -61,6 +61,8 @@ to the server as strings, except for ``gsd`` which it casts to
 properties these will be sent as strings. Some servers may automatically
 cast this to the appropriate data type, others may not.
 
+The query filter will also accept complete JSON as per the specification.
+
 ::
 
     <property><operator><value>

docs/tutorials.rst

@@ -15,7 +15,6 @@ STAC Metadata Visualization
 ---------------------------
 
 - :tutorial:`GitHub version <stac-metadata-viz.ipynb>`
-- :ref:`Docs version </tutorials/stac-metadata-viz.ipynb>`
 
 This tutorial gives an introduction to using Holeviews and hvplot to visualize
 STAC metadata and Item geometries on a map.
@@ -24,7 +23,6 @@ CQL Filtering
 ---------------------------
 
 - :tutorial:`GitHub version <cql-filter.ipynb>`
-- :ref:`Docs version </tutorials/cql-filter.ipynb>`
 
 This tutorial gives an introduction to using CQL-JSON filtering in searches to 
 search by arbitrary STAC Item properties.

docs/tutorials/stac-metadata-viz.ipynb

@@ -233,6 +233,43 @@
    "source": [
     "plot_polygons(aoi_gdf) * items_gdf.hvplot.paths(geo=True)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b0604c84",
+   "metadata": {},
+   "source": [
+    "## Line Plots\n",
+    "\n",
+    "Numeric STAC metadata can also be plotted, most often this will be plotted vs the Item `datetime`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c198e261",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "items_df = pd.DataFrame(items_gdf)\n",
+    "\n",
+    "plot_fields = [\n",
+    "    'properties.eo:cloud_cover',\n",
+    "    'properties.view:sun_azimuth',\n",
+    "    'properties.view:sun_elevation'\n",
+    "]\n",
+    "\n",
+    "plots = None\n",
+    "for f in plot_fields:\n",
+    "    if f in items_df:\n",
+    "        if plots is None:\n",
+    "            plots = items_df.hvplot(y=f, label=f.replace('properties.', ''),\n",
+    "                                    frame_height=500, frame_width=800)\n",
+    "        else:\n",
+    "            plots = plots * items_df.hvplot(y=f, label=f.replace('properties.', ''))\n",
+    "\n",
+    "plots.opts(ylabel='')"
+   ]
   }
  ],
  "metadata": {

docs/usage.rst

@@ -172,18 +172,29 @@ section. See the :mod:`Paging <pystac_client.paging>` docs for details on how to
 Query Filter
 ------------
 
-If the server supports the [query filter](https://github.com/radiantearth/stac-api-spec/tree/master/fragments/query)
-arbitrary Item properties can be included in the search parameters. The query parameter to :class:`ItemSearch` accepts
-a JSON structure as in the STAC API spec, but also accepts an abbreviated syntax. Instead of JSON, a list of strings can
-be provided, in which case pystac-client will convert them to the equivalent JSON structure.
+If the Catalog supports the `Query
+extension <https://github.com/radiantearth/stac-api-spec/tree/master/fragments/query>`__,
+any Item property can also be included in the search. Rather than
+requiring the JSON syntax the Query extension uses, pystac-client can use a
+simpler syntax that it will translate to the JSON equivalent. Note
+however that when the simple syntax is used it sends all property values
+to the server as strings, except for ``gsd`` which it casts to
+``float``. This means that if there are extensions in use with numeric
+properties these will be sent as strings. Some servers may automatically
+cast this to the appropriate data type, others may not.
 
-The syntax is simply:
+The query filter will also accept complete JSON as per the specification.
 
-```
-<property><operator><value>
-e.g.,
+::
 
-eo:cloud_cover<10
-view:off_nadir<50
-platform=landsat-8
-```
+  <property><operator><value>
+
+  where operator is one of `>=`, `<=`, `>`, `<`, `=`
+
+  Examples:
+  eo:cloud_cover<10
+  view:off_nadir<50
+  platform=landsat-8
+
+Any number of properties can be included, and each can be included more
+than once to use additional operators.