Document the group metadata syntax

docs/metadata/data_structures/group.rst

@@ -0,0 +1,63 @@
+Group
+=====
+
+Groups represent sets of plugins, and are a way to concisely and extensibly
+load sets of plugins after other sets of plugins.
+
+This structure can be used to hold group definitions. It is a key-value map.
+
+.. describe:: name
+
+  ``string``
+
+  **Required.** A case-sensitive name that identifies the group.
+
+.. describe:: after
+
+  ``string set``
+
+  The names of groups that this group loads after. Group names are
+  case-sensitive. If undefined, the set is empty. The named groups must be
+  defined when LOOT sorts plugins, but they don't need to be defined in the same
+  metadata file. If at sort time a group is defined to load after a group that
+  does not exist, a sorting error will occur.
+
+Merging Groups
+--------------
+
+When a group definition for an already-defined group is encountered, the
+``after`` sets of the two definitions are merged.
+
+The ``default`` Group
+---------------------
+
+There is one predefined group named ``default`` that all plugins belong to by
+default. It is defined with an empty ``after`` set, as no other predefined
+groups exist for it to load after.
+
+Like any other group, the ``default`` group can be redefined to add group names
+to its ``after`` set.
+
+Equality
+--------
+
+Two group data structures are equal if the values of their ``name`` keys are identical.
+
+Examples
+--------
+
+.. code-block:: yaml
+
+  # Create a group for map marker plugins that loads after the predefined
+  # 'default' group.
+  name: 'Map Markers'
+  after:
+    - 'default'
+
+.. code-block:: yaml
+
+  # Extend the predefined 'default' group to load after an 'Unofficial Patches'
+  # group that is defined elsewhere.
+  name: 'default'
+  after:
+    - 'Unofficial Patches'

docs/metadata/data_structures/index.rst

@@ -9,6 +9,7 @@ LOOT expects metadata to be laid out using a certain set of data structures, des
 
   tag
   file
+  group
   localised_content
   message
   location

docs/metadata/data_structures/plugin.rst

@@ -15,6 +15,21 @@ This is the structure that brings all the others together, and forms the main co
 
   Enables or disables use of the plugin object. Used for user rules, but no reason to use it in the masterlist. If unspecified, defaults to ``true``.
 
+.. describe:: group
+
+  ``string``
+
+  The name of the group the plugin belongs to. If unspecified, defaults to ``default``.
+
+  The named group must be exist when LOOT sorts plugins, but doesn't need to
+  be defined in the same metadata file. If at sort time the group does not
+  exist, a sorting error will occur.
+
+  A plugin must load after all the plugins in the groups its group is defined to
+  load after. Group loading is resolved recursively. For example, if group C
+  loads after group B, and group B loads after group A, a plugin in C must load
+  after all the plugins in A even if no plugins in B are installed.
+
 .. describe:: priority
 
   ``integer``
@@ -99,6 +114,7 @@ Key               Merge Behaviour (merging B into A)
 ===============   ==================================
 name              Not merged.
 enabled           Replaced by B's value.
+group             Replaced by B's value.
 priority          Replaced by B's value, unless that value is ``0`` and it was not explicitly set.
 global_priority   Replaced by B's value, unless that value is ``0`` and it was not explicitly set.
 after             Merged. If B's file set contains an item that is equal to one already present in A's file set, B's item is discarded.