chore: Improve readme (#58)

* Add user-guide example with rasterio

* Add to changelog

* chore: Improve readme

* Use smaller file

Author: maxrjones

README.md

@@ -1,30 +1,54 @@
-# Obspec Utils
+# obspec-utils
 
-[![PyPI - Version](https://img.shields.io/pypi/v/obspec-utils.svg)](https://pypi.org/project/obspec-utils)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/obspec-utils.svg)](https://pypi.org/project/obspec-utils)
+[![PyPI][pypi_badge]][pypi_link]
+[![PyPI - Python Version][python_badge]][pypi_link]
 
------
+[pypi_badge]: https://img.shields.io/pypi/v/obspec-utils.svg
+[pypi_link]: https://pypi.org/project/obspec-utils/
+[python_badge]: https://img.shields.io/pypi/pyversions/obspec-utils.svg
 
-## Table of Contents
+Utilities for cloud data access built on [obspec], fully compatible with [obstore]'s storage classes.
 
-- [Installation](#installation)
-- [License](#license)
+[obspec]: https://github.com/developmentseed/obspec
+[obstore]: https://github.com/developmentseed/obstore
+
+- **File-like readers** that work with xarray, rasterio, h5netcdf, and other libraries expecting file objects.
+- **Composable store wrappers** for caching, request tracing, and splitting large requests.
+- **Glob-style file discovery** with patterns like `data/**/*.nc`, using efficient prefix filtering.
+- **AiohttpStore** for generic HTTPS access (e.g., THREDDS, NASA Earthdata).
 
 ## Installation
 
-```bash
-python -m pip install obspec-utils
+```sh
+pip install obspec-utils
 ```
 
-## Setup development environment
+## Quick Example
+
+```python
+import xarray as xr
+from obstore.store import S3Store
+from obspec_utils.glob import glob
+from obspec_utils.readers import EagerStoreReader
+
+store = S3Store(
+    bucket="its-live-data",
+    aws_region="us-west-2",
+    skip_signature=True,
+)
 
-```console
-git clone https://github.com/virtual-zarr/obspec-utils.git
-cd obspec-utils
-uv sync --all-groups
-uv run --all-groups pytest --cov-config=pyproject.toml --cov=pkg --cov-report xml --cov=src
+# Find NetCDF files matching a pattern
+files = glob(store, "NSIDC/velocity_image_pair_sample/landsatOLI/v02/N20E080/*.nc")
+path = next(files)
+
+with EagerStoreReader(store, path) as reader, xr.open_dataset(reader, engine="h5netcdf") as ds:
+    print(ds)
 ```
 
+## Documentation
+
+Full documentation is available at [obspec-utils.readthedocs.io](https://obspec-utils.readthedocs.io).
+
 ## License
 
 `obspec-utils` is distributed under the terms of the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) license.

tests/test_xarray.py

@@ -52,3 +52,37 @@ def test_eager_reader_xarray_http_store():
 
     # Verify closed is True after context exit
     assert reader.closed is True
+
+
+@pytest.mark.network
+def test_readme_example():
+    """
+    Test the example from the README frontpage.
+
+    Uses ITS_LIVE velocity data from a public S3 bucket.
+    Verifies output matches fsspec.
+    """
+    import s3fs
+    from obstore.store import S3Store
+    from obspec_utils.glob import glob
+
+    bucket = "its-live-data"
+    store = S3Store(
+        bucket=bucket,
+        aws_region="us-west-2",
+        skip_signature=True,
+    )
+
+    # Find NetCDF files matching a pattern
+    files = glob(store, "NSIDC/velocity_image_pair_sample/landsatOLI/v02/N20E080/*.nc")
+    path = files[0]
+
+    fs = s3fs.S3FileSystem(anon=True)
+
+    with (
+        fs.open(f"{bucket}/{path}") as f,
+        EagerStoreReader(store, path) as reader,
+        xr.open_dataset(f, engine="h5netcdf") as ds_fsspec,
+        xr.open_dataset(reader, engine="h5netcdf") as ds_obspec,
+    ):
+        xr.testing.assert_allclose(ds_fsspec.load(), ds_obspec.load())