docs: README updates

stac-utils · Apr 22, 2024 · 23c22a0 · 23c22a0
1 parent 8ccca3b
commit 23c22a0
Show file tree

Hide file tree

Showing 7 changed files with 47 additions and 86 deletions.
diff --git a/README.md b/README.md
@@ -4,57 +4,23 @@
 ![Crates.io](https://img.shields.io/crates/l/stac?style=for-the-badge)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=for-the-badge)](./CODE_OF_CONDUCT)
 
-Rust implementation of the [SpatioTemporal Asset Catalog (STAC)](https://stacspec.org/) specification, spread over several crates.
+Command Line Interface (CLI) and Rust libraries for the [SpatioTemporal Asset Catalog (STAC)](https://stacspec.org/) specification.
 
-<p align="center">
-<img src="https://github.com/radiantearth/stac-site/raw/main/assets/images/STAC-01.png" height="100">
-<img src="https://rustacean.net/assets/rustacean-orig-noshadow.svg" height=100>
-</p>
+- Use [stac-cli](./stac-cli/README.md) to query a STAC API, create and validate STAC items, and do other awesome stuff on the command line.
+- Use the core [stac](./stac/README.md) library to incorporate STAC data structures (`Item`, `Catalog`, and `Collection`) in another Rust application.
+- Use [stac-async](./stac-async/README.md) to build a more complicated application that uses async Rust via [tokio](https://tokio.rs/).
+
+## Crates
+
+This monorepo contains several crates:
 
 | Crate | Description | Badges |
 | ----- | ---- | --------- |
 | [stac](./stac/README.md) | Core data structures and synchronous I/O | [![docs.rs](https://img.shields.io/docsrs/stac?style=flat-square)](https://docs.rs/stac/latest/stac/) <br> [![Crates.io](https://img.shields.io/crates/v/stac?style=flat-square)](https://crates.io/crates/stac) |
 | [stac-validate](./stac-validate/README.md) | Validate STAC data structures with [jsonschema](https://json-schema.org/) | [![docs.rs](https://img.shields.io/docsrs/stac-validate?style=flat-square)](https://docs.rs/stac-validate/latest/stac-validate/) <br> [![Crates.io](https://img.shields.io/crates/v/stac-validate?style=flat-square)](https://crates.io/crates/stac-validate) |
-| [stac-api](./stac-api/README.md) | Data structures for the [STAC API](https://github.com/radiantearth/stac-api-spec) specification | [![docs.rs](https://img.shields.io/docsrs/stac-api?style=flat-square)](https://docs.rs/stac-api/latest/stac_api/) <br> [![Crates.io](https://img.shields.io/crates/v/stac-api?style=flat-square)](https://crates.io/crates/stac-api)
-| [stac-async](./stac-async/README.md) | Asynchronous I/O with [tokio](https://tokio.rs/) | [![docs.rs](https://img.shields.io/docsrs/stac-async?style=flat-square)](https://docs.rs/stac-async/latest/stac_async/) <br> [![Crates.io](https://img.shields.io/crates/v/stac-async?style=flat-square)](https://crates.io/crates/stac-async)
-| [stac-cli](./stac-cli/README.md)| Command line interface | [![docs.rs](https://img.shields.io/docsrs/stac-cli?style=flat-square)](https://docs.rs/stac-cli/latest/stac_cli/) <br> [![Crates.io](https://img.shields.io/crates/v/stac-cli?style=flat-square)](https://crates.io/crates/stac-cli)
-
-## Usage
-
-To use our [command-line interface (CLI)](./stac-cli/README.md), first install Rust, e.g. with [rustup](https://rustup.rs/).
-Then:
-
-```shell
-cargo install stac-cli
-```
-
-Validate a STAC Item:
-
-```shell
-$ stac validate https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json
-OK!
-$ stac validate stac-cli/tests/data/collection-bad-temporal.json 
-Validation error at /extent/temporal: [["2020-12-11T22:38:32.125Z","2020-12-14T18:02:31.437Z"]] is not of type "object"
-ERROR: validation errors
-```
-
-Search a STAC API:
-
-```shell
-stac search https://earth-search.aws.element84.com/v1 \
-    -c sentinel-2-l2a \
-    --max-items 1 \
-    --sortby='-properties.datetime' \
-    --intersects '{"type":"Point","coordinates":[-105.1019,40.1672]}'
-```
-
-To see a full list of available commands:
-
-```shell
-stac --help
-```
-
-The other crates in this repository are libraries — see their respective READMEs and documentation for details on their usage.
+| [stac-api](./stac-api/README.md) | Data structures for the [STAC API](https://github.com/radiantearth/stac-api-spec) specification | [![docs.rs](https://img.shields.io/docsrs/stac-api?style=flat-square)](https://docs.rs/stac-api/latest/stac_api/) <br> [![Crates.io](https://img.shields.io/crates/v/stac-api?style=flat-square)](https://crates.io/crates/stac-api) |
+| [stac-async](./stac-async/README.md) | Asynchronous I/O with [tokio](https://tokio.rs/) | [![docs.rs](https://img.shields.io/docsrs/stac-async?style=flat-square)](https://docs.rs/stac-async/latest/stac_async/) <br> [![Crates.io](https://img.shields.io/crates/v/stac-async?style=flat-square)](https://crates.io/crates/stac-async) |
+| [stac-cli](./stac-cli/README.md)| Command line interface | [![docs.rs](https://img.shields.io/docsrs/stac-cli?style=flat-square)](https://docs.rs/stac-cli/latest/stac_cli/) <br> [![Crates.io](https://img.shields.io/crates/v/stac-cli?style=flat-square)](https://crates.io/crates/stac-cli) |
 
 ## Development
 

diff --git a/stac-api/README.md b/stac-api/README.md
@@ -51,3 +51,7 @@ let root = Root {
 ```
 
 Please see the [documentation](https://docs.rs/stac-api) for more usage examples.
+
+## Other info
+
+This crate is part of the [stac-rs](https://github.com/stac-utils/stac-rs) monorepo, see its README for contributing and license information.
diff --git a/stac-async/README.md b/stac-async/README.md
@@ -27,3 +27,7 @@ let value: stac::Item = tokio_test::block_on(async {
 ```
 
 Please see the [documentation](https://docs.rs/stac-async) for more usage examples.
+
+## Other info
+
+This crate is part of the [stac-rs](https://github.com/stac-utils/stac-rs) monorepo, see its README for contributing and license information.
diff --git a/stac-cli/README.md b/stac-cli/README.md
@@ -6,68 +6,47 @@
 ![Crates.io](https://img.shields.io/crates/l/stac-cli?style=for-the-badge)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=for-the-badge)](./CODE_OF_CONDUCT)
 
-Command line interface to [stac-rs](https://github.com/stac-utils/stac-rs).
+Command Line Interface (CLI) for [STAC](https://stacspec.org/) built with [stac-rs](https://github.com/stac-utils/stac-rs).
+
+![stac-cli gif](./img/stac-cli.gif)
 
 ## Installation
 
-Install rust.
-[rustup](https://rustup.rs/) works well.
-Once you do:
+Install rust, e.g. with [rustup](https://rustup.rs/).
+Then:
 
 ```sh
 cargo install stac-cli
 ```
 
-### Features
+### Homebrew
 
-There is one opt-in feature, `gdal`:
+If you use [homebrew](https://brew.sh/), you can use [gadomski's](https://github.com/gadomski/) tap to install:
 
 ```shell
-cargo install stac-cli -F gdal
+brew install gadomski/gadomski/stac
 ```
 
-This will enable the projection and raster extensions for created items.
-
 ## Usage
 
-Use the cli `--help` flag to see all available options:
-
-```shell
-stac --help
-```
-
-### Item
-
-Create a STAC Item from an href:
-
-```shell
-stac item https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.tif
-```
+**stac-cli** provides the following subcommands:
 
-### Search
+- `stac item`: create STAC items and combine them into item collections
+- `stac search`: search STAC APIs
+- `stac sort`: sort the fields of STAC items, catalogs, and collections
+- `stac validate`: validate STAC items, catalogs, and collections using [json-schema](https://json-schema.org/)
 
-Search a STAC API:
-
-```shell
-stac search https://earth-search.aws.element84.com/v1 \
-    -c sentinel-2-l2a \
-    --max-items 1 \
-    --sortby='-properties.datetime' \
-    --intersects '{"type":"Point","coordinates":[-105.1019,40.1672]}'
-```
+Use the `--help` flag to see all available options for the CLI and the subcommands:
 
-### Validate
+## Features
 
-Validate a STAC item:
+By default, the CLI builds w/ [GDAL](https://gdal.org) support, which requires that GDAL is installed on your system.
+If you don't want to use GDAL, you can disable the default features:
 
 ```shell
-stac validate https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json
+cargo install stac-cli --no-default-features
 ```
 
-### Sort
-
-Sort the fields of a STAC item into the order they're specified in the spec:
+## Other info
 
-```shell
-stac sort https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json
-```
+This crate is part of the [stac-rs](https://github.com/stac-utils/stac-rs) monorepo, see its README for contributing and license information.
diff --git a/stac-cli/img/stac-cli.gif b/stac-cli/img/stac-cli.gif
diff --git a/stac-validate/README.md b/stac-validate/README.md
@@ -27,3 +27,7 @@ item.validate().unwrap();
 ```
 
 Please see the [documentation](https://docs.rs/stac-validate) for more usage examples.
+
+## Other info
+
+This crate is part of the [stac-rs](https://github.com/stac-utils/stac-rs) monorepo, see its README for contributing and license information.
diff --git a/stac/README.md b/stac/README.md
@@ -119,3 +119,7 @@ This is mostly useful for auto-generating OpenAPI documentation for STAC APIs.
 [dependencies]
 stac = { version = "0.6", features = ["schemars"]}
 ```
+
+## Other info
+
+This crate is part of the [stac-rs](https://github.com/stac-utils/stac-rs) monorepo, see its README for contributing and license information.