Docs: Explicitly state that AiiDA's Group API and CLI can be used (#…

…170)

It is not directly obvious to users that AiiDA's group APIs can be used
with pseudopotential families since they are simply groups themselves.

docs/source/design.rst

@@ -53,6 +53,12 @@ Families
 ========
 
 Having loose pseudopotentials floating around is not very practical, so groups of related pseudopotentials can be organized into "families", which are implemented as group plugins with the base class :py:class:`~aiida_pseudo.groups.family.PseudoPotentialFamily`.
+
+.. tip::
+
+    Since a :py:class:`~aiida_pseudo.groups.family.PseudoPotentialFamily` is a subclass of AiiDA's :py:class:`~aiida.orm.groups.Group`, they share the same API.
+    That means you can use `AiiDA's group API <https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/data.html#organizing-data>`_ as well as the ``verdi group`` CLI to work with families of ``aiida-pseudo``.
+
 A family class can in principle support many pseudopotential formats, however, a family instance can only contain pseudopotentials of a single format.
 For example, the :py:class:`~aiida_pseudo.groups.family.PseudoPotentialFamily` class supports all of the pseudopotential formats that are supported by this plugin.
 However, any instance can only contain pseudopotentials of the same format (e.g. *all* UPF or *all* PSP8, not a mixture).

docs/source/howto.rst

@@ -211,3 +211,33 @@ If the snippet finishes successfully, you can run ``verdi group list -a`` which
 
 .. _SSSP: https://www.materialscloud.org/discover/sssp/table/efficiency
 .. _Pseudo Dojo: http://www.pseudo-dojo.org/
+
+
+Working with families
+=====================
+
+Since a :class:`~aiida_pseudo.groups.family.PseudoPotentialFamily` is a subclass of AiiDA's :class:`~aiida.orm.groups.Group`, they share the same API.
+That means you can use `AiiDA's group API <https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/data.html#organizing-data>`_ as well as the ``verdi group`` CLI to work with pseudopotential families.
+For example, to load a family in the Python API, simply use :func:`aiida.orm.utils.loaders.load_group`:
+
+.. code-block:: python
+
+    from aiida.orm import load_group
+    family = load_group('family-label')
+
+Once loaded, the :class:`~aiida.orm.groups.Group` API can be used to modify the family:
+
+.. code-block:: python
+
+    from aiida.orm import load_group
+    family = load_group('family-label')
+    pseudo = list(family.nodes)[0]  # Get a random pseudo
+    family.remove_nodes([pseudo])  # Remove the pseudo from the family
+    family.add_nodes([pseudo])  # Add the removed pseudo again
+
+Like the Python API, the commands of AiiDA's CLI ``verdi group`` also accept pseudopotential families.
+
+.. note::
+
+    ``verdi group list`` does not list ``aiida-pseudo`` families by default, because they are a custom ``Group`` plugin.
+    To include pseudopotential families, add the ``-a`` option, i.e., ``verdi group list -a``.