From 70311636ec80f7c5e65beb6bbab79b5966c98c90 Mon Sep 17 00:00:00 2001
From: Chris Barnes <barnesc@janelia.hhmi.org>
Date: Wed, 17 Jul 2019 14:16:44 -0400
Subject: [PATCH] documentation

---
 README.rst     | 32 +++++++++++++++++++++++++++++---
 docs/usage.rst | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+), 3 deletions(-)

diff --git a/README.rst b/README.rst
index e7f907f..2351ed9 100644
--- a/README.rst
+++ b/README.rst
@@ -6,6 +6,9 @@ pyn5
 .. image:: https://img.shields.io/pypi/v/pyn5.svg
         :target: https://pypi.python.org/pypi/pyn5
 
+.. image:: https://img.shields.io/pypi/pyversions/pyn5.svg
+        :target: https://pypi.python.org/pypi/pyn5
+
 .. image:: https://travis-ci.org/pattonw/rust-pyn5.svg?branch=master
         :target: https://travis-ci.org/pattonw/rust-pyn5
 
@@ -14,19 +17,36 @@ pyn5
         :alt: Documentation Status
 
 
-
-
 Python wrapper around rust-n5.
 
 
 * Free software: MIT license
 * Documentation: https://rust-pyn5.readthedocs.io.
 
+Installation
+------------
+
+``pip install pyn5`` installs pre-compiled wheels.
+To build from source, you need
+
+* `setuptools-rust`_
+* a rust_ compiler
+
+  - >= 1.34.0-nightly 2019-02-06
+  - <= 1.36.0-nightly 2019-07-01
 
 Features
 --------
 
-* TODO
+* h5py-like interface
+
+Related projects
+----------------
+
+* N5_ (file system format spec and reference implementation in java)
+* `rust-n5`_ (implementation in rust, used in pyn5)
+* zarr_ (similar chunked array storage library and format, supports some N5 features)
+* z5_ (C++ implementation of zarr and N5 with python bindings, depends on conda)
 
 Credits
 -------
@@ -35,3 +55,9 @@ This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypack
 
 .. _Cookiecutter: https://github.com/audreyr/cookiecutter
 .. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
+.. _N5: https://github.com/saalfeldlab/n5/
+.. _rust-n5: https://github.com/aschampion/rust-n5/
+.. _zarr: https://zarr-developers.github.io/
+.. _z5: https://github.com/constantinpape/z5/
+.. _setuptools-rust: https://github.com/PyO3/setuptools-rust
+.. _rust: https://www.rust-lang.org/tools/install
diff --git a/docs/usage.rst b/docs/usage.rst
index 444523e..5c5ff64 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -5,3 +5,52 @@ Usage
 To use pyn5 in a project::
 
     import pyn5
+
+pyn5 exposes an API largely compatible with h5py_.
+There are additionally some enums defined to optionally help manage open modes and compression types
+
+
+.. code-block:: python
+
+    import numpy as np
+
+    from pyn5 import File, Mode, CompressionType
+
+    f = File("path/to/test.n5", mode=Mode.READ_WRITE_CREATE)  # default mode 'a'
+
+    g1 = f.create_group("group1")
+    g2 = f.require_group("/group1/group2")
+    ds1 = g2.create_dataset(
+        "dataset1",
+        data=np.random.random((10, 10)),
+        chunks=(5, 5),
+        compression=CompressionType.GZIP,
+        compression_opts=-1
+    )  # default compression
+
+    # indexing supports slices, integers, ellipses, and newaxes
+    arr = ds1[:, 5, np.newaxes]
+
+    ds1.attrs["key"] = "value"
+
+
+Differences from h5py
+---------------------
+
+* The HDF5_ format is different to N5_; refer to their specifications
+* No files are held open, so there is no need to use a context manager (``with``) to open a ``File``
+
+  - But you can use one if you want, for compatibility
+
+* Attributes must be JSON-serializable
+
+  - The default encoder will convert numpy arrays to nested lists; they will remain lists when read
+
+* Compression types are as described in the N5_ spec
+* Group and Dataset copying and linking are not supported
+* Non-zero fill values, dataset resizing, and named dimensions are not supported
+
+
+.. _HDF5: https://support.hdfgroup.org/HDF5/doc/H5.format.html
+.. _h5py: http://docs.h5py.org/en/stable/
+.. _N5: https://github.com/saalfeldlab/n5/#file-system-specification-version-203-snapshot