docs: add docstring to ScalarMapJSON type, and fix TOC for api docs

Author: d-v-b

README.md

@@ -59,9 +59,13 @@ precision lost due to rounding is acceptable.
 ## how
 
 ```python
+# import the codec that uses the rust backend
+from cast_value import CastValueRustV1
+
 # Create an in-memory zarr array with float64 dtype, stored as uint8.
 # The cast_value codec handles the conversion: float64 -> uint8 on write,
 # uint8 -> float64 on read.
+
 codec = CastValueRustV1(
     data_type="uint8",
     rounding="nearest-even",

docs/api.md

@@ -1,29 +1,21 @@
 # Python API
 
-## Types
-
-::: cast_value.types.RoundingMode
-
-::: cast_value.types.OutOfRangeMode
-
-::: cast_value.types.NumericScalar
-
-::: cast_value.types.ScalarMapEntry
+## Zarr Codec
 
-::: cast_value.types.ScalarMapJSON
+::: cast_value.CastValueRustV1
 
-## Core
+::: cast_value.CastValueNumpyV1
 
-::: cast_value.core.cast_array
+::: cast_value.cast_array
 
-::: cast_value.core.round_inplace
+::: cast_value.ScalarMapJSON
 
-::: cast_value.core.check_int_range
+::: cast_value.ScalarMapEntry
 
-::: cast_value.core.apply_scalar_map
+::: cast_value.ScalarMapEntries
 
-## Zarr Codec
+::: cast_value.RoundingMode
 
-::: cast_value.zarr_compat.v1.CastValueNumpyV1
+::: cast_value.OutOfRangeMode
 
-::: cast_value.zarr_compat.v1.CastValueRustV1
+::: cast_value.NumericScalar

docs/index.md

@@ -25,7 +25,7 @@ pip install cast-value[rs]
 ```python
 import numpy as np
 import zarr
-from cast_value.zarr_compat.v1 import CastValueNumpyV1
+from cast_value import CastValueNumpyV1
 
 zarr.registry.register_codec("cast_value", CastValueNumpyV1)
 
@@ -56,6 +56,6 @@ Two backends are available:
 - **`CastValueRustV1`** — Rust via
   [cast-value-rs](https://pypi.org/project/cast-value-rs/). Faster for
   non-default rounding modes and SIMD-accelerated float-to-integer casts with
-  clamping.
+  clamping, with more efficient memory usage.
 
 Both implement the same codec interface and produce identical results.

src/cast_value/types.py

@@ -19,7 +19,14 @@
 
 
 class ScalarMapJSON(TypedDict):
-    """JSON representation of the scalar_map codec configuration field."""
+    """
+    JSON representation of the scalar_map codec configuration field.
+
+    This type models permitted values for the [`scalar_map`](https://github.com/zarr-developers/zarr-extensions/tree/main/codecs/cast_value#scalar_map) field in the
+    [`configuration`](https://github.com/zarr-developers/zarr-extensions/tree/main/codecs/cast_value#configuration) field of the `cast_value` codec metadata.
+
+    See the [`cast_value` spec](https://github.com/zarr-developers/zarr-extensions/tree/main/codecs/cast_value) for details.
+    """
 
     encode: NotRequired[list[tuple[object, object]]]
     decode: NotRequired[list[tuple[object, object]]]