Add docs for storage mapping (#48)

* Add documention on the Zarr storage definition * Updated changelog Co-authored-by: Ben Dichter <[email protected]> Co-authored-by: mavaylon1 <[email protected]>
hdmf-dev · Dec 22, 2022 · 6841196 · 6841196
1 parent 5d2811d
commit 6841196
Show file tree

Hide file tree

Showing 5 changed files with 373 additions and 11 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,11 +4,12 @@
 
 ### Bugs
 * Use path relative to the current Zarr file in the definition of links and references to avoid breaking
-  links when moving Zarr files @oruebel ([#46](https://github.com/hdmf-dev/hdmf-zarr/pull/46))
-* Fix bugs in requirements defined in setup.py @oruebel ([#46](https://github.com/hdmf-dev/hdmf-zarr/pull/46))
+  links when moving Zarr files @oruebel [#46](https://github.com/hdmf-dev/hdmf-zarr/pull/46)
+* Fix bugs in requirements defined in setup.py @oruebel [#46](https://github.com/hdmf-dev/hdmf-zarr/pull/46)
 
 ### Docs
-* Add tutoial illustrating how to create a new NWB file with NWBZarrIO @oruebel ([#46](https://github.com/hdmf-dev/hdmf-zarr/pull/46))
+* Add tutoial illustrating how to create a new NWB file with NWBZarrIO @oruebel [#46](https://github.com/hdmf-dev/hdmf-zarr/pull/46)
+* Add docs for describing the mapping of HDMF schema to Zarr storage @oruebel [#48](https://github.com/hdmf-dev/hdmf-zarr/pull/48)
 
 ## 0.1.0 
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -89,7 +89,8 @@
 # Use this for mapping to external links
 extlinks = {
     'pynwb-docs': ('https://pynwb.readthedocs.io/en/stable/', '%s'),
-    'hdmf-docs': ('https://hdmf.readthedocs.io/en/stable/', ''),
+    'hdmf-docs': ('https://hdmf.readthedocs.io/en/stable/', '%s'),
+    'zarr-docs': ('https://zarr.readthedocs.io/en/stable/', '%s')
 }
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -30,6 +30,7 @@ Citing hdmf-zarr
    :maxdepth: 2
    :caption: For Developers:
 
+   storage
    hdmf_zarr
 
 Indices and tables

diff --git a/docs/source/overview.rst b/docs/source/overview.rst
@@ -10,11 +10,8 @@ Zarr Backend and Utilities
 * :py:class:`~hdmf_zarr.nwb.NWBZarrIO` uses :py:class:`~hdmf_zarr.backend.ZarrIO` to define a Zarr backend store for integration with PyNWB to simplify the use of `hdmf_zarr` with NWB (similar to :py:class:`~pynwb.NWBHDF5IO` in PyNWB)
 * :py:mod:`~hdmf_zarr.utils` implements utility classes for the :py:class:`~hdmf_zarr.backend.ZarrIO` backend. For end-users the :py:class:`~hdmf_zarr.utils.ZarrDataIO` class is relevant for defining advanced I/O options for datasets.
 
-Features and Known Limitations
-------------------------------
-
 Supported features
-^^^^^^^^^^^^^^^^^^^
+------------------
 
 - Write/Read of basic data types, strings and compound data types
 - Chunking
@@ -24,11 +21,11 @@ Supported features
 - Writing/loading namespaces/specifications
 - Iterative data write using :py:class:`~hdmf.data_utils.AbstractDataChunkIterator`
 
-Limitations
-^^^^^^^^^^^
+Known Limitations
+-----------------
 
+- Support for region references is not yet implemented. See also :ref:`sec-zarr-storage-references-region` for details.
 - The Zarr backend is currently experimental and may still change.
-- Support for region references is not yet implemented  (see `hdmf-zarr issue #47 <https://github.com/hdmf-dev/hdmf-zarr/issues/47>`_.
 - Attributes are stored as JSON documents in Zarr (using the DirectoryStore). As such, all attributes must be JSON serializable. The :py:class:`~hdmf_zarr.backend.ZarrIO` backend attempts to cast types to JSON serializable types as much as possible.
 - Currently the :py:class:`~hdmf_zarr.backend.ZarrIO` backend uses Zarr's :py:class:`~zarr.storage.DirectoryStore` only. Other `Zarr stores <https://zarr.readthedocs.io/en/stable/api/storage.html>`_ could be added but will require proper treatment of links and references for those backends as links are not supported in Zarr (see `zarr-python issues #389 <https://github.com/zarr-developers/zarr-python/issues/389>`_.
 - Exporting of HDF5 files with external links is not yet fully implemented/tested. (see `hdmf-zarr issue #49 <https://github.com/hdmf-dev/hdmf-zarr/issues/49>`_.