docs: Docstring formatting updates

ARCHITECTURE.md

@@ -14,6 +14,7 @@ src/lazycogs/
   _grid.py           output affine transform and grid dimensions
   _reproject.py      warp-map computation and nearest-neighbor sampling
   _storage_ext.py    STAC Storage Extension metadata parsing
+  _single.py         open_cog()/open_item(): native-resolution single-COG and single-item reads
   _store.py          HREF-to-store resolution and store_for()
   _temporal.py       temporal grouping strategies and _TimeStep predicates
   _mosaic_methods.py pixel-selection strategies

README.md

@@ -41,7 +41,7 @@ y label `0` is the northernmost pixel and `y[-1]` is the southernmost.  This
 matches the affine transform and is consistent with `odc-stac`, `rioxarray`, and
 GDAL.
 
-Use ``sel(y=slice(north, south))`` (high to low) for spatial subsetting.
+Use `sel(y=slice(north, south))` (high to low) for spatial subsetting.
 
 `x` and `y` keep their `RasterIndex`-based spatial selection behavior, but the
 coordinate variables themselves are materialized eagerly so chunked nearest-neighbor
@@ -83,6 +83,35 @@ da = lazycogs.open(
 )
 ```
 
+### Single COG and single item reads
+
+Sometimes you don't want a reprojected mosaic — you want to read one asset (or
+a few bands of one item) exactly as stored. `lazycogs.open_cog` and
+`lazycogs.open_item` read COGs **at their native grid** (native CRS, resolution,
+and shape, no reprojection), returning eagerly-loaded `(band, y, x)` DataArrays
+with the same rioxarray-compatible metadata as `lazycogs.open`.
+
+```python
+import lazycogs
+
+# One COG → (band, y, x) at native resolution, band labelled 1..N.
+da = lazycogs.open_cog("s3://bucket/scene/B04.tif")
+
+# Several same-grid assets of one STAC item, stacked and labelled by asset key.
+# `item` is a STAC item dict (e.g. a rustac search result) or a pystac Item.
+da = lazycogs.open_item(item, bands=["B04", "B08"])
+# da.dims == ("band", "y", "x"); da["band"] == ["B04", "B08"]
+```
+
+`open_item` requires every selected asset to be a single-band COG sharing the
+same native grid (CRS, resolution, extent); it raises a `ValueError` otherwise.
+`nodata`/`scale`/`offset` are read from each asset file and surfaced as scalar
+CF attributes (`_FillValue`/`scale_factor`/`add_offset`) only when all selected
+bands agree. For assets at differing resolutions, or to mosaic across a whole
+collection, use `lazycogs.open` instead. Both functions accept the same
+`store=`/`path_from_href=` arguments as `lazycogs.open`, and each has an
+`await`-able `_async` variant (`open_cog_async`, `open_item_async`).
+
 ### Temporal grouping
 
 By default, `lazycogs.open()` groups items into one time step per calendar day (`time_period="P1D"`). You can also request coarser composites with `"PnD"`, `"P1W"`, `"P1M"`, or `"P1Y"`.

dev-docs/specs/rasterix-spatial-index.md

@@ -153,7 +153,7 @@ attributes = {
 | `height` | `dst_height` | From `compute_output_grid()`. |
 | `x_dim` | `"x"` | Matches existing lazycogs dimension name. |
 | `y_dim` | `"y"` | Matches existing lazycogs dimension name. |
-| `crs` | `dst_crs` | ``pyproj.CRS`` object passed to ``open()``. |
+| `crs` | `dst_crs` | `pyproj.CRS` object passed to `open()`. |
 
 ### Metadata attributes
 

dev-docs/specs/resampling-methods.md

@@ -226,9 +226,9 @@ def apply_interp_map(
 ) -> np.ndarray:
     """Resample source array using fractional coordinates and an interpn kernel.
 
-    The source ``data`` is assumed to be the enlarged read window (including halo).
-    Coordinates in ``interp_map`` are shifted by the window origin before evaluation
-    so that they are relative to the sub-array passed to ``interpn``.
+    The source `data` is assumed to be the enlarged read window (including halo).
+    Coordinates in `interp_map` are shifted by the window origin before evaluation
+    so that they are relative to the sub-array passed to `interpn`.
     """
     ...
 ```

docs/api/single.md

@@ -0,0 +1,17 @@
+# Single COG / item
+
+Read a single Cloud-Optimized GeoTIFF or the assets of one STAC item at their
+native grid — no reprojection or mosaicking. Use `lazycogs.open` for a
+reprojected mosaic across a whole collection.
+
+!!! tip "See also"
+    [Loading single item on native grid](../notebooks/single-item.ipynb)
+
+::: lazycogs.open_cog
+
+::: lazycogs.open_item
+
+::: lazycogs.open_cog_async
+
+::: lazycogs.open_item_async
+

docs/index.md

@@ -15,7 +15,7 @@ y label `0` is the northernmost pixel and `y[-1]` is the southernmost.  This
 matches the affine transform and is consistent with `odc-stac`, `rioxarray`, and
 GDAL.
 
-Use ``sel(y=slice(north, south))`` (high to low) for spatial subsetting.
+Use `sel(y=slice(north, south))` (high to low) for spatial subsetting.
 
 ## What is lazycogs?