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,15 +1,23 @@
-# 🐍 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}`ngff_zarr.ngff_image.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
 
@@ -165,3 +173,8 @@ 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/