DAS-2155: Reorder, and fix bullet list

doc/user-guide/data-structures.rst

@@ -619,12 +619,86 @@ Alternatively you can also create a ``DataTree`` object from
 - A dictionary mapping directory-like paths to either ``DataTree`` nodes or
   data, using :py:meth:`xarray.DataTree.from_dict()`,
 - A well formed netCDF or Zarr file on disk with
-:py:func:`open_datatree()`. See :ref:`reading and writing files <io>`.  For
-data files with groups that do not not align see :py:func:`xarray.open_groups()` or use
-:py:func:`xarray.open_dataset(group='target_group')`
+:py:func:`open_datatree()`. See :ref:`reading and writing files <io>`.
 
+For data files with groups that do not not align see
+:py:func:`xarray.open_groups()` or use
+:py:func:`xarray.open_dataset(group='target_group')`. For more information
+about coordinate alignment see :ref:`datatree-inheritance`
 
-DataTree Inheritence
+
+
+DataTree Contents
+~~~~~~~~~~~~~~~~~
+
+Like ``xarray.Dataset``, ``xarray.DataTree`` implements the python mapping interface,
+but with values given by either ``xarray.DataArray`` objects or other
+``DataTree`` objects.
+
+.. ipython:: python
+
+    dt["a"]
+    dt["foo"]
+
+Iterating over keys will iterate over both the names of variables and child nodes.
+
+We can also access all the data in a single node through a dataset-like view
+
+.. ipython:: python
+
+    dt["a"].ds
+
+This demonstrates the fact that the data in any one node is equivalent to the
+contents of a single ``xarray.Dataset`` object. The ``DataTree.ds`` property
+returns an immutable view, but we can instead extract the node's data contents
+as a new (and mutable) ``xarray.Dataset`` object via
+:py:meth:`xarray.DataTree.to_dataset()`:
+
+.. ipython:: python
+
+    dt["a"].to_dataset()
+
+Like with ``Dataset``, you can access the data and coordinate variables of a
+node separately via the ``data_vars`` and ``coords`` attributes:
+
+.. ipython:: python
+
+    dt["a"].data_vars
+    dt["a"].coords
+
+
+Dictionary-like methods
+~~~~~~~~~~~~~~~~~~~~~~~
+
+We can update a datatree in-place using Python's standard dictionary syntax,
+similar to how we can for Dataset objects. For example, to create this example
+datatree from scratch, we could have written:
+
+.. ipython:: python
+
+    dt = xr.DataTree(name="root")
+    dt["foo"] = "orange"
+    dt["a"] = xr.DataTree(data=xr.Dataset({"bar": 0}, coords={"y": ("y", [0, 1, 2])}))
+    dt["a/b/zed"] = np.nan
+    dt
+
+To change the variables in a node of a ``DataTree``, you can use all the
+standard dictionary methods, including ``values``, ``items``, ``__delitem__``,
+``get`` and :py:meth:`xarray.DataTree.update`.
+Note that assigning a ``DataArray`` object to a ``DataTree`` variable using
+``__setitem__`` or ``update`` will :ref:`automatically align <update>` the
+array(s) to the original node's indexes.
+
+If you copy a ``DataTree`` using the :py:func:`copy` function or the
+:py:meth:`xarray.DataTree.copy` method it will copy the subtree,
+meaning that node and children below it, but no parents above it.
+Like for ``Dataset``, this copy is shallow by default, but you can copy all the
+underlying data arrays by calling ``dt.copy(deep=True)``.
+
+
+.. _datatree-inheritance:
+
+DataTree Inheritance
 ~~~~~~~~~~~~~~~~~~~~
 
 DataTree implements a simple inheritance mechanism. Coordinates and their
@@ -658,7 +732,7 @@ Some examples:
     infrared = xr.DataArray(np.ones((2, 3, 3)) * 6, dims=("time", "lon", "lat"))
     true_color = xr.DataArray(np.ones((2, 3, 3)) * 7, dims=("time", "lon", "lat"))
 
-    dt = xr.DataTree.from_dict(
+    dt2 = xr.DataTree.from_dict(
         {
             "/": xr.Dataset(
                 coords={"time": times},
@@ -705,75 +779,8 @@ automatically include coordinates from higher levels (e.g., time):
 
 .. ipython:: python
 
-    dt["/weather_data/temperature"].ds
-
-
-DataTree Contents
-~~~~~~~~~~~~~~~~~
-
-Like ``xarray.Dataset``, ``xarray.DataTree`` implements the python mapping interface,
-but with values given by either ``xarray.DataArray`` objects or other
-``DataTree`` objects.
-
-.. ipython:: python
-
-    dt["a"]
-    dt["foo"]
-
-Iterating over keys will iterate over both the names of variables and child nodes.
+    dt2["/weather_data/temperature"].ds
 
-We can also access all the data in a single node through a dataset-like view
-
-.. ipython:: python
-
-    dt["a"].ds
-
-This demonstrates the fact that the data in any one node is equivalent to the
-contents of a single ``xarray.Dataset`` object. The ``DataTree.ds`` property
-returns an immutable view, but we can instead extract the node's data contents
-as a new (and mutable) ``xarray.Dataset`` object via
-:py:meth:`xarray.DataTree.to_dataset()`:
-
-.. ipython:: python
-
-    dt["a"].to_dataset()
-
-Like with ``Dataset``, you can access the data and coordinate variables of a
-node separately via the ``data_vars`` and ``coords`` attributes:
-
-.. ipython:: python
-
-    dt["a"].data_vars
-    dt["a"].coords
-
-
-Dictionary-like methods
-~~~~~~~~~~~~~~~~~~~~~~~
-
-We can update a datatree in-place using Python's standard dictionary syntax,
-similar to how we can for Dataset objects. For example, to create this example
-datatree from scratch, we could have written:
-
-.. ipython:: python
-
-    dt = xr.DataTree(name="root")
-    dt["foo"] = "orange"
-    dt["a"] = xr.DataTree(data=xr.Dataset({"bar": 0}, coords={"y": ("y", [0, 1, 2])}))
-    dt["a/b/zed"] = np.nan
-    dt
-
-To change the variables in a node of a ``DataTree``, you can use all the
-standard dictionary methods, including ``values``, ``items``, ``__delitem__``,
-``get`` and :py:meth:`xarray.DataTree.update`.
-Note that assigning a ``DataArray`` object to a ``DataTree`` variable using
-``__setitem__`` or ``update`` will :ref:`automatically align <update>` the
-array(s) to the original node's indexes.
-
-If you copy a ``DataTree`` using the :py:func:`copy` function or the
-:py:meth:`xarray.DataTree.copy` method it will copy the subtree,
-meaning that node and children below it, but no parents above it.
-Like for ``Dataset``, this copy is shallow by default, but you can copy all the
-underlying data arrays by calling ``dt.copy(deep=True)``.
 
 .. _coordinates: