[designspaceLib] Add "description" to <mappings> and <mapping>

Fixes https://github.com/fonttools/fonttools/issues/3435

Doc/source/designspaceLib/xml.rst

@@ -263,11 +263,14 @@ Example of all axis elements together
 ``<mappings>`` element
 ======================
 
--  Define axis mappings.
+-  Define an axis mappings group.
 -  Child element of ``axes``
 
+.. rubric:: Attributes
 
- .. versionadded:: 5.1
+- ``description``: optional, string. the description of this mappings group
+
+ .. versionadded:: 5.2
 
 
 ``<mapping>`` element
@@ -276,8 +279,11 @@ Example of all axis elements together
 -  Defines an axis mapping.
 -  Child element of ``<mappings>``
 
+.. rubric:: Attributes
 
- .. versionadded:: 5.1
+- ``description``: optional, string. the description of this mapping
+
+ .. versionadded:: 5.2
 
 
 ``<input>`` element

Lib/fontTools/designspaceLib/__init__.py

@@ -476,7 +476,14 @@ class AxisMappingDescriptor(SimpleDescriptor):
 
     _attrs = ["inputLocation", "outputLocation"]
 
-    def __init__(self, *, inputLocation=None, outputLocation=None):
+    def __init__(
+        self,
+        *,
+        inputLocation=None,
+        outputLocation=None,
+        description=None,
+        groupDescription=None,
+    ):
         self.inputLocation: SimpleLocationDict = inputLocation or {}
         """dict. Axis values for the input of the mapping, in design space coordinates.
 
@@ -491,6 +498,20 @@ class AxisMappingDescriptor(SimpleDescriptor):
 
         .. versionadded:: 5.1
         """
+        self.description = description
+        """string. A description of the mapping.
+
+        varLib.
+
+        .. versionadded:: 5.2
+        """
+        self.groupDescription = groupDescription
+        """string. A description of the group of mappings.
+
+        varLib.
+
+        .. versionadded:: 5.2
+        """
 
 
 class InstanceDescriptor(SimpleDescriptor):
@@ -1421,10 +1442,19 @@ class BaseDocWriter(object):
             self._addAxis(axisObject)
 
         if self.documentObject.axisMappings:
-            mappingsElement = ET.Element("mappings")
+            mappingsElement = None
-            self.root.findall(".axes")[0].append(mappingsElement)
+            lastGroup = object()
             for mappingObject in self.documentObject.axisMappings:
+                if getattr(mappingObject, "groupDescription", None) != lastGroup:
+                    if mappingsElement is not None:
+                        self.root.findall(".axes")[0].append(mappingsElement)
+                    lastGroup = getattr(mappingObject, "groupDescription", None)
+                    mappingsElement = ET.Element("mappings")
+                    if lastGroup is not None:
+                        mappingsElement.attrib["description"] = lastGroup
                 self._addAxisMapping(mappingsElement, mappingObject)
+            if mappingsElement is not None:
+                self.root.findall(".axes")[0].append(mappingsElement)
 
         if self.documentObject.locationLabels:
             labelsElement = ET.Element("labels")
@@ -1586,6 +1616,8 @@ class BaseDocWriter(object):
 
     def _addAxisMapping(self, mappingsElement, mappingObject):
         mappingElement = ET.Element("mapping")
+        if getattr(mappingObject, "description", None) is not None:
+            mappingElement.attrib["description"] = mappingObject.description
         for what in ("inputLocation", "outputLocation"):
             whatObject = getattr(mappingObject, what, None)
             if whatObject is None:
@@ -2081,10 +2113,11 @@ class BaseDocReader(LogMixin):
             self.documentObject.axes.append(axisObject)
             self.axisDefaults[axisObject.name] = axisObject.default
 
-        mappingsElement = self.root.find(".axes/mappings")
         self.documentObject.axisMappings = []
-        if mappingsElement is not None:
+        for mappingsElement in self.root.findall(".axes/mappings"):
+            groupDescription = mappingsElement.attrib.get("description")
             for mappingElement in mappingsElement.findall("mapping"):
+                description = mappingElement.attrib.get("description")
                 inputElement = mappingElement.find("input")
                 outputElement = mappingElement.find("output")
                 inputLoc = {}
@@ -2098,7 +2131,10 @@ class BaseDocReader(LogMixin):
                     value = float(dimElement.attrib["xvalue"])
                     outputLoc[name] = value
                 axisMappingObject = self.axisMappingDescriptorClass(
-                    inputLocation=inputLoc, outputLocation=outputLoc
+                    inputLocation=inputLoc,
+                    outputLocation=outputLoc,
+                    description=description,
+                    groupDescription=groupDescription,
                 )
                 self.documentObject.axisMappings.append(axisMappingObject)
 

Tests/designspaceLib/data/test_avar2.designspace

@@ -19,8 +19,8 @@
       <map input="87.5" output="89"/>
       <map input="100" output="100"/>
     </axis>
-    <mappings>
+    <mappings description="all mappings">
-      <mapping>
+      <mapping description="test mapping">
         <input>
 	  <dimension name="Justify" xvalue="-100"/>
 	  <dimension name="Width" xvalue="100"/>

Tests/designspaceLib/designspace_test.py

@@ -720,6 +720,12 @@ def test_axisMappingsRoundtrip(tmpdir):
     assert [mapping.outputLocation for mapping in doc.axisMappings] == [
         mapping.outputLocation for mapping in doc2.axisMappings
     ]
+    assert [mapping.description for mapping in doc.axisMappings] == [
+        mapping.description for mapping in doc2.axisMappings
+    ]
+    assert [mapping.groupDescription for mapping in doc.axisMappings] == [
+        mapping.groupDescription for mapping in doc2.axisMappings
+    ]
 
 
 def test_rulesConditions(tmpdir):