Docs: add example of writing and reading groups to netcdf (#7338)

* example of writing and reading groups to netcdf

* whatsnew

Author: TomNicholas

doc/user-guide/io.rst

@@ -162,11 +162,77 @@ To do so, pass a ``group`` keyword argument to the
 :py:func:`open_dataset` function. The group can be specified as a path-like
 string, e.g., to access subgroup ``'bar'`` within group ``'foo'`` pass
 ``'/foo/bar'`` as the ``group`` argument.
+
 In a similar way, the ``group`` keyword argument can be given to the
 :py:meth:`Dataset.to_netcdf` method to write to a group
 in a netCDF file.
 When writing multiple groups in one file, pass ``mode='a'`` to
 :py:meth:`Dataset.to_netcdf` to ensure that each call does not delete the file.
+For example:
+
+.. ipython::
+    :verbatim:
+
+    In [1]: ds1 = xr.Dataset({"a": 0})
+
+    In [2]: ds2 = xr.Dataset({"b": 1})
+
+    In [3]: ds1.to_netcdf("file.nc", group="A")
+
+    In [4]: ds2.to_netcdf("file.nc", group="B", mode="a")
+
+We can verify that two groups have been saved using the ncdump command-line utility.
+
+.. code:: bash
+
+    $ ncdump file.nc
+    netcdf file {
+
+    group: A {
+      variables:
+        int64 a ;
+      data:
+
+       a = 0 ;
+      } // group A
+
+    group: B {
+      variables:
+        int64 b ;
+      data:
+
+       b = 1 ;
+      } // group B
+    }
+
+Either of these groups can be loaded from the file as an independent :py:class:`Dataset` object:
+
+.. ipython::
+    :verbatim:
+
+    In [1]: group1 = xr.open_dataset("file.nc", group="A")
+
+    In [2]: group1
+    Out[2]:
+    <xarray.Dataset>
+    Dimensions:  ()
+    Data variables:
+        a        int64 ...
+
+    In [3]: group2 = xr.open_dataset("file.nc", group="B")
+
+    In [4]: group2
+    Out[4]:
+    <xarray.Dataset>
+    Dimensions:  ()
+    Data variables:
+        b        int64 ...
+
+.. note::
+
+    For native handling of multiple groups with xarray, including I/O, you might be interested in the experimental
+    `xarray-datatree <https://github.com/xarray-contrib/datatree>`_ package.
+
 
 .. _io.encoding:
 

doc/whats-new.rst

@@ -69,6 +69,8 @@ Bug fixes
 Documentation
 ~~~~~~~~~~~~~
 
+- Add example of reading and writing individual groups to a single netCDF file to I/O docs page. (:pull:`7338`)
+  By `Tom Nicholas <https://github.com/TomNicholas>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~