Add docs for storage mapping

CHANGELOG.md

@@ -1,5 +1,8 @@
 # HDMF-ZARR Changelog
 
+## 0.1.x (Upcoming)
+- Add docs for describing the mapping of HDMF schema to Zarr storage
+
 ## 0.1.0 
 
 ### New features

docs/source/conf.py

@@ -58,6 +58,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.extlinks',
     'sphinx.ext.napoleon',
     'sphinx_gallery.gen_gallery',
 ]
@@ -85,6 +86,13 @@
     'zarr': ('https://zarr.readthedocs.io/en/stable/', None)
 }
 
+# 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/', '%s'),
+    'zarr-docs': ('https://zarr.readthedocs.io/en/stable/', '%s')
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/source/index.rst

@@ -30,6 +30,7 @@ Citing hdmf-zarr
    :maxdepth: 2
    :caption: For Developers:
 
+   storage
    hdmf_zarr
 
 Indices and tables

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,12 +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 :py:class:`hdmf_zarr.backend.ZarrIO.__get_ref`)
+- 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.
-- Links and reference are not natively supported by Zarr. Links and references are implemented in :py:class:`~hdmf_zarr.backend.ZarrIO` in an OS independent fashion. The backend reserves attributes (see :py:attr:`~hdmf_zarr.backend.ZarrIO.__reserve_attribute`) to store the paths of the target objects (see also  :py:meth:`~hdmf_zarr.backend.ZarrIO.__write_link__`, :py:meth:`~hdmf_zarr.backend.ZarrIO.__add_link__`, :py:meth:`~hdmf_zarr.backend.ZarrIO.__read_links`)
 - 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 `https://github.com/zarr-developers/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