From 5b67a1c2f59823f24b1115cf5cc8c25c635e7e19 Mon Sep 17 00:00:00 2001 From: Ryan Ly Date: Sun, 12 Jan 2025 10:09:40 -0800 Subject: [PATCH] Update docs and links to Zarr v2 (#257) --- CHANGELOG.md | 1 + README.rst | 4 +++- docs/gallery/plot_nwb_zarrio.py | 2 +- docs/source/conf.py | 4 ++-- docs/source/index.rst | 7 +++++-- docs/source/overview.rst | 2 +- 6 files changed, 13 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c735419..58a101e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ * Adopted changelog format conventions: https://keepachangelog.com/en/1.0.0/ . @rly [#254](https://github.com/hdmf-dev/hdmf-zarr/pull/254) * Made docs site point to latest stable release: https://hdmf-zarr.readthedocs.io/en/stable/ instead of "latest" tag. @rly [#254](https://github.com/hdmf-dev/hdmf-zarr/pull/254) * Removed GitHub Actions workflow that automatically generated GitHub pre-releases on the "latest" tag on each commit to dev to simplify maintenance. @rly [#254](https://github.com/hdmf-dev/hdmf-zarr/pull/254) +* Clarified docs and updated links to say that only Zarr v2 is currently supported. @rly [#257](https://github.com/hdmf-dev/hdmf-zarr/pull/257) ## 0.10.0 (December 18, 2024) diff --git a/README.rst b/README.rst index 5b7daf52..ec54781c 100644 --- a/README.rst +++ b/README.rst @@ -4,10 +4,12 @@ hdmf-zarr ========= -The ``hdmf-zarr`` library implements a Zarr backend for HDMF as well as convenience classes for integration of Zarr with PyNWB to support writing of NWB files to Zarr. +The ``hdmf-zarr`` library implements a Zarr v2 backend for HDMF as well as convenience classes for integration of Zarr with PyNWB to support writing of NWB files to Zarr. **Status:** The Zarr backend is **under development** and may still change. See the `overiew page `_ for an overview of the available features and known limitations of hdmf-zarr. +Support for Zarr v3 is planned. You can track progress of the support in https://github.com/hdmf-dev/hdmf-zarr/issues/202. + Documentation Status -------------------- diff --git a/docs/gallery/plot_nwb_zarrio.py b/docs/gallery/plot_nwb_zarrio.py index eacceddc..d5f77cc0 100644 --- a/docs/gallery/plot_nwb_zarrio.py +++ b/docs/gallery/plot_nwb_zarrio.py @@ -153,5 +153,5 @@ # Even when the metadata is consolidated, the metadata natively within the file can be altered. # Any alterations within would require the user to call `zarr.convenience.consolidate_metadata()` # to sync the file with the changes. Please refer to the Zarr documentation for more details: -# https://zarr.readthedocs.io/en/stable/tutorial.html#storage-alternatives +# https://zarr.readthedocs.io/en/v2.18.4/tutorial.html#storage-alternatives zarr.consolidate_metadata(path) diff --git a/docs/source/conf.py b/docs/source/conf.py index d6c4f697..65ca8efc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -83,14 +83,14 @@ 'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None), 'hdmf': ('https://hdmf.readthedocs.io/en/stable/', None), 'pynwb': ('https://pynwb.readthedocs.io/en/stable/', None), - 'zarr': ('https://zarr.readthedocs.io/en/stable/', None) + 'zarr': ('https://zarr.readthedocs.io/en/v2.18.4/', None) } # Use this for mapping to external links extlinks = { 'pynwb-docs': ('https://pynwb.readthedocs.io/en/stable/%s', '%s'), 'hdmf-docs': ('https://hdmf.readthedocs.io/en/stable/%s', '%s'), - 'zarr-docs': ('https://zarr.readthedocs.io/en/stable/%s', '%s') + 'zarr-docs': ('https://zarr.readthedocs.io/en/v2.18.4/%s', '%s') } # Add any paths that contain templates here, relative to this directory. diff --git a/docs/source/index.rst b/docs/source/index.rst index f9910075..c46d4e7b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,13 +6,16 @@ Welcome to hdmf-zarr's documentation! ===================================== -**hdmf_zarr** implements a Zarr backend for `HDMF `_ as well as +**hdmf_zarr** implements a Zarr v2 backend for `HDMF `_ as well as convenience classes for integration of Zarr with `PyNWB `_ to -support writing of NWB files to `Zarr `_. +support writing of NWB files to `Zarr v2 `_. **Status:** The Zarr backend is **under development** and may still change. See the :ref:`sec-overview` section for a description of available features and known limitations of hdmf-zarr. +Support for Zarr v3 is planned. You can track progress of the support in https://github.com/hdmf-dev/hdmf-zarr/issues/202. + + Citing hdmf-zarr ^^^^^^^^^^^^^^^^ diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 690bc8f5..0de01f96 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -31,6 +31,6 @@ Known Limitations - The Zarr backend is currently experimental and may still change. - 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 supports Zarr's directory-based stores :py:class:`~zarr.storage.DirectoryStore`, :py:class:`~zarr.storage.NestedDirectoryStore`, and :py:class:`~zarr.storage.TempStore`. Other `Zarr stores `_ 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 `_. +- Currently the :py:class:`~hdmf_zarr.backend.ZarrIO` backend supports Zarr's directory-based stores :py:class:`~zarr.storage.DirectoryStore`, :py:class:`~zarr.storage.NestedDirectoryStore`, and :py:class:`~zarr.storage.TempStore`. Other `Zarr stores `_ 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 `_. - Exporting of HDF5 files with external links is not yet fully implemented/tested. (see `hdmf-zarr issue #49 `_. - Special characters (e.g., ``:``, ``<``, ``>``, ``"``, ``/``, ``\``, ``|``, ``?``, or ``*``) may not be supported by all file systems (e.g., on Windows) and as such should not be used as part of the names of Datasets or Groups as Zarr needs to create folders on the filesystem for these objects.