Added docs page on io (#158)

* added page on io

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* whatsnew

* fix typo which inverted meaning of key sentence

* fix headings and link

* add missing links

* fix final link

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: TomNicholas

docs/source/index.rst

@@ -12,6 +12,7 @@ Datatree
    Quick Overview <quick-overview>
    Tutorial <tutorial>
    Data Model <data-structures>
+   Reading and Writing Files <io>
    API Reference <api>
    How do I ... <howdoi>
    Contributing Guide <contributing>

docs/source/io.rst

@@ -0,0 +1,52 @@
+.. _data structures:
+
+Reading and Writing Files
+=========================
+
+.. note::
+
+    This page builds on the information given in xarray's main page on
+    `reading and writing files <https://docs.xarray.dev/en/stable/user-guide/io.html>`_,
+    so it is suggested that you are familiar with those first.
+
+
+netCDF
+------
+
+Groups
+~~~~~~
+
+Whilst netCDF groups can only be loaded individually as Dataset objects, a whole file of many nested groups can be loaded
+as a single ``:py:class::DataTree`` object.
+To open a whole netCDF file as a tree of groups use the ``:py:func::open_datatree()`` function.
+To save a DataTree object as a netCDF file containing many groups, use the ``:py:meth::DataTree.to_netcdf()`` method.
+
+
+.. _netcdf.group.warning:
+
+.. warning::
+    ``DataTree`` objects do not follow the exact same data model as netCDF files, which means that perfect round-tripping
+    is not always possible.
+
+    In particular in the netCDF data model dimensions are entities that can exist regardless of whether any variable possesses them.
+    This is in contrast to `xarray's data model <https://docs.xarray.dev/en/stable/user-guide/data-structures.html>`_
+    (and hence :ref:`datatree's data model<data structures>`) in which the dimensions of a (Dataset/Tree)
+    object are simply the set of dimensions present across all variables in that dataset.
+
+    This means that if a netCDF file contains dimensions but no variables which possess those dimensions,
+    these dimensions will not be present when that file is opened as a DataTree object.
+    Saving this DataTree object to file will therefore not preserve these "unused" dimensions.
+
+Zarr
+----
+
+Groups
+~~~~~~
+
+Nested groups in zarr stores can be represented by loading the store as a ``:py:class::DataTree`` object, similarly to netCDF.
+To open a whole zarr store as a tree of groups use the ``:py:func::open_datatree()`` function.
+To save a DataTree object as a zarr store containing many groups, use the ``:py:meth::DataTree.to_zarr()`` method.
+
+.. note::
+    Note that perfect round-tripping should always be possible with a zarr store (:ref:`unlike for netCDF files<netcdf.group.warning>`),
+    as zarr does not support "unused" dimensions.

docs/source/whats-new.rst

@@ -40,6 +40,9 @@ Bug fixes
 Documentation
 ~~~~~~~~~~~~~
 
+- Added ``Reading and Writing Files`` page. (:pull:`158`)
+  By `Tom Nicholas <https://github.com/TomNicholas>`_.
+
 Internal Changes
 ~~~~~~~~~~~~~~~~