DAS-2155 - Merge datatree documentation into main docs.

ci/requirements/doc.yml

@@ -37,7 +37,8 @@ dependencies:
   - sphinx-copybutton
   - sphinx-design
   - sphinx-inline-tabs
-  - sphinx>=5.0
+  - sphinx=6.2.1  # sphinx-book-theme issue: 749
+  - sphinxcontrib-srclinks
   - sphinxext-opengraph
   - sphinxext-rediraffe
   - zarr>=2.10

doc/api.rst

@@ -588,6 +588,298 @@ Reshaping and reorganizing
    DataArray.sortby
    DataArray.broadcast_like
 
+DataTree
+========
+
+Creating a DataTree
+-------------------
+
+Methods of creating a ``DataTree``.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree
+   DataTree.from_dict
+
+Tree Attributes
+---------------
+
+Attributes relating to the recursive tree-like structure of a ``DataTree``.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.parent
+   DataTree.children
+   DataTree.name
+   DataTree.path
+   DataTree.root
+   DataTree.is_root
+   DataTree.is_leaf
+   DataTree.leaves
+   DataTree.level
+   DataTree.depth
+   DataTree.width
+   DataTree.subtree
+   DataTree.descendants
+   DataTree.siblings
+   DataTree.lineage
+   DataTree.parents
+   DataTree.ancestors
+   DataTree.groups
+
+Data Contents
+-------------
+
+Interface to the data objects (optionally) stored inside a single ``DataTree`` node.
+This interface echoes that of ``xarray.Dataset``.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.dims
+   DataTree.sizes
+   DataTree.data_vars
+   DataTree.coords
+   DataTree.attrs
+   DataTree.encoding
+   DataTree.indexes
+   DataTree.nbytes
+   DataTree.ds
+   DataTree.to_dataset
+   DataTree.has_data
+   DataTree.has_attrs
+   DataTree.is_empty
+   DataTree.is_hollow
+
+Dictionary Interface
+--------------------
+
+``DataTree`` objects also have a dict-like interface mapping keys to either ``xarray.DataArray``s or to child ``DataTree`` nodes.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.__getitem__
+   DataTree.__setitem__
+   DataTree.__delitem__
+   DataTree.update
+   DataTree.get
+   DataTree.items
+   DataTree.keys
+   DataTree.values
+
+Tree Manipulation
+-----------------
+
+For manipulating, traversing, navigating, or mapping over the tree structure.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.orphan
+   DataTree.same_tree
+   DataTree.relative_to
+   DataTree.iter_lineage
+   DataTree.find_common_ancestor
+   DataTree.map_over_subtree
+   DataTree.pipe
+   DataTree.match
+   DataTree.filter
+
+Pathlib-like Interface
+----------------------
+
+``DataTree`` objects deliberately echo some of the API of :py:class:`pathlib.PurePath`.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.name
+   DataTree.parent
+   DataTree.parents
+   DataTree.relative_to
+
+Missing:
+
+..
+
+   ``DataTree.glob``
+   ``DataTree.joinpath``
+   ``DataTree.with_name``
+   ``DataTree.walk``
+   ``DataTree.rename``
+   ``DataTree.replace``
+
+DataTree Contents
+-----------------
+
+Manipulate the contents of all nodes in a ``DataTree`` simultaneously.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.copy
+   DataTree.assign_coords
+   DataTree.merge
+   DataTree.rename
+   DataTree.rename_vars
+   DataTree.rename_dims
+   DataTree.swap_dims
+   DataTree.expand_dims
+   DataTree.drop_vars
+   DataTree.drop_dims
+   DataTree.set_coords
+   DataTree.reset_coords
+
+DataTree Node Contents
+----------------------
+
+Manipulate the contents of a single ``DataTree`` node.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.assign
+   DataTree.drop_nodes
+
+Comparisons
+-----------
+
+Compare one ``DataTree`` object to another.
+
+.. autosummary::
+   :toctree: generated/
+
+    DataTree.isomorphic
+    DataTree.equals
+    DataTree.identical
+
+Indexing
+--------
+
+Index into all nodes in the subtree simultaneously.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.isel
+   DataTree.sel
+   DataTree.drop_sel
+   DataTree.drop_isel
+   DataTree.head
+   DataTree.tail
+   DataTree.thin
+   DataTree.squeeze
+   DataTree.interp
+   DataTree.interp_like
+   DataTree.reindex
+   DataTree.reindex_like
+   DataTree.set_index
+   DataTree.reset_index
+   DataTree.reorder_levels
+   DataTree.query
+
+..
+
+   Missing:
+   ``DataTree.loc``
+
+
+Missing Value Handling
+----------------------
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.isnull
+   DataTree.notnull
+   DataTree.combine_first
+   DataTree.dropna
+   DataTree.fillna
+   DataTree.ffill
+   DataTree.bfill
+   DataTree.interpolate_na
+   DataTree.where
+   DataTree.isin
+
+Computation
+-----------
+
+Apply a computation to the data in all nodes in the subtree simultaneously.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.map
+   DataTree.reduce
+   DataTree.diff
+   DataTree.quantile
+   DataTree.differentiate
+   DataTree.integrate
+   DataTree.map_blocks
+   DataTree.polyfit
+   DataTree.curvefit
+
+Aggregation
+-----------
+
+Aggregate data in all nodes in the subtree simultaneously.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.all
+   DataTree.any
+   DataTree.argmax
+   DataTree.argmin
+   DataTree.idxmax
+   DataTree.idxmin
+   DataTree.max
+   DataTree.min
+   DataTree.mean
+   DataTree.median
+   DataTree.prod
+   DataTree.sum
+   DataTree.std
+   DataTree.var
+   DataTree.cumsum
+   DataTree.cumprod
+
+ndarray methods
+---------------
+
+Methods copied from :py:class:`numpy.ndarray` objects, here applying to the data in all nodes in the subtree.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.argsort
+   DataTree.astype
+   DataTree.clip
+   DataTree.conj
+   DataTree.conjugate
+   DataTree.round
+   DataTree.rank
+
+Reshaping and reorganising
+--------------------------
+
+Reshape or reorganise the data in all nodes in the subtree.
+
+.. autosummary::
+   :toctree: generated/
+
+   DataTree.transpose
+   DataTree.stack
+   DataTree.unstack
+   DataTree.shift
+   DataTree.roll
+   DataTree.pad
+   DataTree.sortby
+   DataTree.broadcast_like
+
 IO / Conversion
 ===============
 
@@ -652,6 +944,22 @@ DataArray methods
    DataArray.load
    DataArray.unify_chunks
 
+DataTree methods
+----------------
+
+.. autosummary::
+   :toctree: generated/
+
+   xarray.backends.api.open_datatree
+   DataTree.to_dict
+   DataTree.to_netcdf
+   DataTree.to_zarr
+
+..
+
+   Missing:
+   ``open_mfdatatree``
+
 Coordinates objects
 ===================
 
@@ -1071,6 +1379,15 @@ Testing
    testing.assert_allclose
    testing.assert_chunks_equal
 
+Test that two ``DataTree`` objects are similar.
+
+.. autosummary::
+   :toctree: generated/
+
+   testing.assert_isomorphic
+   testing.assert_equal
+   testing.assert_identical
+
 Hypothesis Testing Strategies
 =============================
 
@@ -1101,6 +1418,18 @@ Exceptions
    MergeError
    SerializationWarning
 
+DataTree
+--------
+
+Exceptions raised when manipulating trees.
+
+.. autosummary::
+   :toctree: generated/
+
+   xarray.TreeIsomorphismError
+   xarray.InvalidTreeError
+   xarray.NotFoundInTreeError
+
 Advanced API
 ============
 
@@ -1110,6 +1439,7 @@ Advanced API
    Coordinates
    Dataset.variables
    DataArray.variable
+   DataTree.variables
    Variable
    IndexVariable
    as_variable
@@ -1118,12 +1448,18 @@ Advanced API
    Context
    register_dataset_accessor
    register_dataarray_accessor
+   xarray.core.extensions.register_datatree_accessor
    Dataset.set_close
    backends.BackendArray
    backends.BackendEntrypoint
    backends.list_engines
    backends.refresh_engines
 
+..
+
+   Missing:
+   ``DataTree.set_close``
+
 Default, pandas-backed indexes built-in Xarray:
 
    indexes.PandasIndex