WIP: DOC: Improved Python interface docs

Author: thewtex

docs/index.md

@@ -29,7 +29,7 @@ A lean and kind
 
 quick_start.md
 installation.md
-array_api.md
+python.md
 cli.md
 itk.md
 methods.md

docs/itk.md

@@ -8,7 +8,7 @@ Bidirectional type conversion that preserves spatial metadata is available with
 Once represented as an `NgffImage`, a multiscale representation can be generated
 with `to_multiscales`. And an OME-Zarr can be generated from the multiscales
 with `to_ngff_zarr`. For more information, see the
-[Python Array API documentation](./array_api.md).
+[Python interface documentation](./python.md).
 
 ## ITK Python
 

docs/array_api.md renamed to docs/python.md

@@ -1,24 +1,30 @@
-# 🐍 Python Array API
+# 🐍 Python Interface
 
-NGFF-Zarr supports conversion of any NumPy array-like object that follows the
-[Python Array API Standard](https://data-apis.org/array-api/latest/) into
-OME-Zarr. This includes such objects an NumPy `ndarray`'s, Dask Arrays, PyTorch
-Tensors, CuPy arrays, Zarr array, etc.
+NGFF-Zarr is a Python library that provides a simple, natural interface for
+working with OME-Zarr data structures, creating chunked, multiscale OME-Zarr
+image pyramids, and reading and writing OME-Zarr multiscale image files.
+
+NGFF-Zarr's interface, which reflects the OME-Zarr data model, is built on
+Python's built-in [dataclasses] and [Dask arrays]. It is designed to be simple,
+flexible, and easy to use.
 
 ## Array to NGFF Image
 
-Convert the array to an `NgffImage`, which is a standard
-[Python dataclass](https://docs.python.org/3/library/dataclasses.html) that
-represents an OME-Zarr image for a single scale.
+NGFF-Zarr supports conversion of any NumPy array-like object that follows the
+[Python Array API Standard] into the OME-Zarr data model. This includes such
+objects an NumPy `ndarray`'s, Dask Arrays, PyTorch Tensors, CuPy arrays, Zarr
+array, etc.
+
+Convert the array to an [`NgffImage`], which is a standard Python [dataclass]
+that represents an OME-Zarr image for a single scale.
 
 When creating the image from the array, you can specify
 
 - names of the `dims` from `{‘t’, ‘z’, ‘y’, ‘x’, ‘c’}`
 - the `scale`, the pixel spacing for the spatial dims
 - the `translation`, the origin or offset of the center of the first pixel
 - a `name` for the image
-- and `axes_units` with
-  [UDUNITS-2 identifiers](https://ngff.openmicroscopy.org/latest/#axes-md)
+- and `axes_units` with [UDUNITS-2 identifiers]
 
 ```python
 >>> # Load an image as a NumPy array
@@ -152,7 +158,7 @@ scale according the OME-Zarr data model. Note that the correct `scale` and
 
 ## Write to Zarr
 
-To write the multiscales to Zarr, use `to_ngff_zarr`.
+To write the multiscales to Zarr, use [`to_ngff_zarr`].
 
 ```python
 nz.to_ngff_zarr('cthead1.ome.zarr', multiscales)
@@ -165,3 +171,11 @@ Any other
 also be used.
 
 The multiscales will be computed and written out-of-core, limiting memory usage.
+
+[dataclass]: https://docs.python.org/3/library/dataclasses.html
+[dataclasses]: https://docs.python.org/3/library/dataclasses.html
+[Dask arrays]: https://docs.dask.org/en/stable/array.html
+[Python Array API Standard]: https://data-apis.org/array-api/latest/
+[UDUNITS-2 identifiers]: https://ngff.openmicroscopy.org/latest/#axes-md
+[`NgffImage`]: ./apidocs/ngff_zarr/ngff_zarr.ngff_image.html
+[`to_ngff_zarr`]: ./apidocs/ngff_zarr/ngff_zarr.to_ngff_zarr.html