📝 Copy example usage to crate-level docs as doctest

Copy the Rust code from 15b0dbc to src/lib.rs as a doctest. Need to change `crate-type = ["rlib"]` in Cargo.toml so that `cargo test --doc` works, but will configure that in CI later.

Cargo.toml

@@ -16,7 +16,7 @@ numpy = "0.20.0"
 object_store = { version = "0.9.0", features = ["http"] }
 pyo3 = { version = "0.20.3", features = ["abi3-py310", "extension-module"] }
 tiff = "0.9.1"
-tokio = "1.36.0"
+tokio = { version = "1.36.0", features = ["rt-multi-thread"] }
 url = "2.5.0"
 
 [dev-dependencies]

README.md

@@ -55,6 +55,7 @@ async fn main() {
 
     let arr: Array2<f32> = read_geotiff(stream).unwrap();
     assert_eq!(arr.dim(), (549, 549));
+    assert_eq!(arr[[500, 500]], 0.13482364);
 }
 ```
 

src/lib.rs

@@ -8,6 +8,41 @@
 //! **Note**: For Python users, there are also bindings (via [`pyo3`]) to read GeoTIFF files into
 //! `numpy.ndarray` objects (i.e. similar to [`rasterio`](https://github.com/rasterio/rasterio)).
 //! This is done via the [`numpy`] crate which enables passing data from Rust to Python.
+//!
+//! # Examples
+//!
+//! Read a GeoTIFF file retrieved via the [`object_store`] crate, and pass it into the
+//! [`read_geotiff`](./io/geotiff/fn.read_geotiff.html) function.
+//!
+//! ```rust
+//! use std::io::Cursor;
+//!
+//! use bytes::Bytes;
+//! use cog3pio::io::geotiff::read_geotiff;
+//! use ndarray::Array2;
+//! use object_store::path::Path;
+//! use object_store::{parse_url, GetResult, ObjectStore};
+//! use tokio;
+//! use url::Url;
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     let cog_url: &str =
+//!         "https://github.com/cogeotiff/rio-tiler/raw/6.4.0/tests/fixtures/cog_nodata_nan.tif";
+//!     let tif_url: Url = Url::parse(cog_url).unwrap();
+//!     let (store, location): (Box<dyn ObjectStore>, Path) = parse_url(&tif_url).unwrap();
+//!
+//!     let stream: Cursor<Bytes> = {
+//!         let result: GetResult = store.get(&location).await.unwrap();
+//!         let bytes: Bytes = result.bytes().await.unwrap();
+//!         Cursor::new(bytes)
+//!     };
+//!
+//!     let arr: Array2<f32> = read_geotiff(stream).unwrap();
+//!     assert_eq!(arr.dim(), (549, 549));
+//!     assert_eq!(arr[[500, 500]], 0.13482364);
+//! }
+//! ```
 
 /// Modules for handling Input/Output of GeoTIFF data
 pub mod io;