Terminology

docs/source/index.rst

@@ -14,6 +14,7 @@ Datatree
    Data Model <data-structures>
    Reading and Writing Files <io>
    API Reference <api>
+   Terminology <terminology>
    How do I ... <howdoi>
    Contributing Guide <contributing>
    Development Roadmap <roadmap>

docs/source/terminology.rst

@@ -0,0 +1,33 @@
+.. currentmodule:: datatree
+.. _terminology:
+
+This page extends `xarray's page on terminology <https://docs.xarray.dev/en/stable/user-guide/terminology.html>`_.
+
+Terminology
+===========
+
+.. glossary::
+
+    DataTree
+        A tree-like collection of ``Dataset`` objects. A *tree* is made up of one or more *nodes*,
+        each of which can store the same information as a single ``Dataset`` (accessed via `.ds`).
+        This data is stored in the same way as in a ``Dataset``, i.e. in the form of data variables
+        (see **Variable** in the `corresponding xarray terminology page <https://docs.xarray.dev/en/stable/user-guide/terminology.html>`_),
+        dimensions, coordinates, and attributes.
+
+        The nodes in a tree are linked to one another, and each node is it's own instance of ``DataTree`` object.
+        Each node can have zero or more *children* (stored in a dictionary-like manner under their corresponding *names*),
+        and those child nodes can themselves have children.
+        If a node is a child of another node that other node is said to be its *parent*. Nodes can have a maximum of one parent,
+        and if a node has no parent it is said to be the *root* node of that *tree*.
+
+    Subtree
+        A section of a *tree*, consisting of a *node* along with all the child nodes below it
+        (and the child nodes below them, i.e. all so-called *descendant* nodes).
+        Excludes the parent node and all nodes above.
+
+    Group
+        Another word for a subtree, reflecting how the hierarchical structure of a ``DataTree`` allows for grouping related data together.
+        Analogous to a single
+        `netCDF group <https://www.unidata.ucar.edu/software/netcdf/workshops/2011/groups-types/GroupsIntro.html>`_ or
+        `Zarr group <https://zarr.readthedocs.io/en/stable/tutorial.html#groups>`_.

docs/source/whats-new.rst

@@ -58,6 +58,8 @@ Documentation
   By `Tom Nicholas <https://github.com/TomNicholas>`_.
 - Changed docs theme to match xarray's main documentation. (:pull:`173`)
   By `Tom Nicholas <https://github.com/TomNicholas>`_.
+- Added ``Terminology`` page. (:pull:`174`)
+  By `Tom Nicholas <https://github.com/TomNicholas>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~