Document the group metadata syntax

docs/api/reference.rst

@@ -54,6 +54,9 @@ Classes
 .. doxygenclass:: loot::File
    :members:
 
+.. doxygenclass:: loot::Group
+   :members:
+
 .. doxygenclass:: loot::Location
    :members:
 

docs/api/sorting.rst

@@ -25,7 +25,8 @@ Create plugin graph vertices
 
 Once loaded, a directed graph is created and the plugins are added to it in
 lexicographical order as vertices. Any metadata a plugin has in the masterlist
-and userlist are then merged into its vertex's data store.
+and userlist are then merged into its vertex's data store. Plugin group
+dependencies are also resolved and added as additional load after plugins.
 
 Create plugin graph edges
 ==============================

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.

docs/metadata/file_structure.rst

@@ -10,13 +10,18 @@ The root of a metadata file is a key-value map. LOOT will recognise the followin
 
   A list of Bash Tags that are supported by the masterlist's game. These Bash Tags are used to provide autocomplete suggestions in LOOT's metadata editor.
 
-
 .. describe:: globals
 
   message list
 
   A list of message data structures for messages that are displayed independently of any plugin.
 
+.. describe:: groups
+
+  group set
+
+  A set of group data structures that represent the groups that plugins can belong to.
+
 .. describe:: plugins
 
   plugin list *and* plugin set
@@ -33,20 +38,29 @@ Example
   bash_tags:
     - 'C.Climate'
     - 'Relev'
+
   globals:
     - type: say
       content: 'You are using the latest version of LOOT.'
- condition: 'version("LOOT", "0.5.0.0", ==)'
-    plugins:
-      - name: 'Armamentarium.esm'
-        tag:
-          - Relev
-      - name: 'ArmamentariumFran.esm'
-        tag:
-          - Relev
-      - name: 'Beautiful People 2ch-Ed.esm'
-        tag:
-          - Eyes
-          - Graphics
-          - Hair
-          - R.Relations
+      condition: 'version("LOOT", "0.5.0.0", ==)'
+
+  groups:
+    - name: 'Map Markers'
+      after:
+        - 'default'
+
+  plugins:
+    - name: 'Armamentarium.esm'
+      tag:
+        - Relev
+    - name: 'ArmamentariumFran.esm'
+      tag:
+        - Relev
+    - name: 'Beautiful People 2ch-Ed.esm'
+      tag:
+        - Eyes
+        - Graphics
+        - Hair
+        - R.Relations
+    - name: 'More Map Markers.esp'
+      group: 'Map Markers'