From d513e563ff444e903760cbbd894733ad01696179 Mon Sep 17 00:00:00 2001
From: Behdad Esfahbod <behdad@behdad.org>
Date: Tue, 30 May 2023 21:57:26 -0600
Subject: [PATCH] [designspaceLib/avar2] Add XML docs

---
 Doc/source/designspaceLib/xml.rst        | 67 +++++++++++++++++++++++-
 Lib/fontTools/designspaceLib/__init__.py |  4 +-
 2 files changed, 67 insertions(+), 4 deletions(-)

diff --git a/Doc/source/designspaceLib/xml.rst b/Doc/source/designspaceLib/xml.rst
index ee4edef1c..20952c6f8 100644
--- a/Doc/source/designspaceLib/xml.rst
+++ b/Doc/source/designspaceLib/xml.rst
@@ -20,10 +20,15 @@ Overview
 .. code:: xml
 
     <?xml version='1.0' encoding='utf-8'?>
-    <designspace format="5.0">
+    <designspace format="5.1">
         <axes>
             <!-- define axes here -->
             <axis... />
+            <mappings>
+                <!-- define axis mappings here -->
+                <!-- New in version 5.1 -->
+                <mapping... />
+            </mappings>
         </axes>
         <labels>
             <!-- define STAT format 4 labels here -->
@@ -255,6 +260,64 @@ Example of all axis elements together
     </axes>
 
 
+``<mappings>`` element
+======================
+
+-  Define axis mappings.
+-  Child element of ``axes``
+
+
+ .. versionadded:: 5.1
+
+
+``<mapping>`` element
+---------------------
+
+-  Defines an axis mapping.
+-  Child element of ``<mappings>``
+
+
+ .. versionadded:: 5.1
+
+
+``<input>`` element
+...................
+
+-  Defines the input location of an axis mapping.
+-  Child element of ``<mapping>``
+-  Contains one or more ``<dimension>`` elements with designspace locations.
+
+ .. versionadded:: 5.1
+
+
+``<output>`` element
+...................
+
+-  Defines the output location of an axis mapping.
+-  Child element of ``<mapping>``
+-  Contains one or more ``<dimension>`` elements with designspace locations.
+
+ .. versionadded:: 5.1
+
+
+Example of all mappings elements together
+=========================================
+
+.. code:: xml
+
+    <mappings>
+        <mapping>
+            <input>
+                <dimension name="weight" xvalue="900"/>
+                <dimension name="width" xvalue="150"/>
+            </input>
+            <output>
+                <dimension name="weight" xvalue="870"/>
+            </output>
+        </mapping>
+    </mappings>
+
+
 ================================
 ``<labels>`` element (top-level)
 ================================
@@ -304,7 +367,7 @@ See: `OTSpec STAT Axis value table, format 4 <https://docs.microsoft.com/en-us/t
 ``<dimension>`` element
 .......................
 
--  Child element of ``<location>``
+-  Child element of ``<location>``, ``input``, or ``output`` elements
 
 .. rubric:: Attributes
 
diff --git a/Lib/fontTools/designspaceLib/__init__.py b/Lib/fontTools/designspaceLib/__init__.py
index 02b06c8cc..06dd5f67a 100644
--- a/Lib/fontTools/designspaceLib/__init__.py
+++ b/Lib/fontTools/designspaceLib/__init__.py
@@ -484,14 +484,14 @@ class AxisMappingDescriptor(SimpleDescriptor):
 
         Varlib.
 
-        .. versionadded:: REPLACEME
+        .. versionadded:: 5.1
         """
         self.outputLocation: SimpleLocationDict = outputLocation or {}
         """dict. Axis values for the output of the mapping, in design space coordinates.
 
         Varlib.
 
-        .. versionadded:: REPLACEME
+        .. versionadded:: 5.1
         """