Add an example on scripting with designSpaceDocument.

Lib/designSpaceDocument/__init__.py

@@ -5,21 +5,14 @@ import os
 import xml.etree.ElementTree as ET
 
 """
-
     designSpaceDocument
 
     - read and write designspace files
     - axes must be defined.
     - warpmap is stored in its axis element
-
 """
 
-
-__all__ = [
-    'DesignSpaceDocumentError', 'BaseDocReader', 'DesignSpaceDocument',
-    'SourceDescriptor', 'InstanceDescriptor',
-    'AxisDescriptor', 'BaseDocReader', 'BaseDocWriter']
-
+__all__ = [ 'DesignSpaceDocumentError', 'BaseDocReader', 'DesignSpaceDocument', 'SourceDescriptor', 'InstanceDescriptor', 'AxisDescriptor', 'BaseDocReader', 'BaseDocWriter']
 
 class DesignSpaceDocumentError(Exception):
     def __init__(self, msg, obj=None):
@@ -643,6 +636,12 @@ class DesignSpaceDocument(object):
                     fonts.append((f, sourceDescriptor.location))
         return fonts
 
+    def getAxisOrder(self):
+        names = []
+        for axisDescriptor in self.axes:
+            names.append(axisDescriptor.name)
+        return names
+
 
 if __name__ == "__main__":
 

scirpting.md

@@ -0,0 +1,99 @@
+# Scripting a designspace
+
+It can be useful to build a designspace with a script rather than construct one with an interface like [Superpolator](http://superpolator.com) or [DesignSpaceEditor](https://github.com/LettError/designSpaceRoboFontExtension). But the [designSpaceDocument](https://github.com/LettError/designSpaceDocument) also offers a method of building designspaces in Python. This document offers some examples on how to do that.
+
+So, suppose you installed the [designSpaceDocument](https://github.com/LettError/designSpaceDocument) package through your favorite `git` client.
+
+The `DesignSpaceDocument` object represents the document, whether it already exists or not. Make a new one:
+
+```python
+import os
+from designSpaceDocument import DesignSpaceDocument, AxisDescriptor, SourceDescriptor, InstanceDescriptor
+doc = DesignSpaceDocument()
+```
+
+We want to create definitions for axes, sources and instances. That means a lot of attributes to set, so the **DesignSpaceDocument object** uses objects to descibe the axes, sources and instances. These are relatively simple objects, just a collection of attributes.
+
+* [Source descriptor](https://github.com/LettError/designSpaceDocument#source-descriptor-object-attributes) attributes and example.
+* [Instance descriptor](https://github.com/LettError/designSpaceDocument#instance-descriptor-object)  attributes and example.
+* [Axis descriptor](https://github.com/LettError/designSpaceDocument#axis-descriptor-object)  attributes and example.
+* Read about [subclassing descriptors](https://github.com/LettError/designSpaceDocument#subclassing-descriptors)
+
+## Making some axes
+
+Make a descriptor object and add it to the document.
+
+```python
+a1 = AxisDescriptor()
+a1.initial = 0
+a1.maximum = 1000
+a1.minimum = 0
+a1.default = 0
+a1.name = "weight"
+a1.tag = "wght"
+doc.addAxis(a1)
+```
+You can add as many axes as you need. OpenType has a maximum of around 64K. DesignSpaceEditor has a maximum of 5.
+
+## Make a source object
+
+A **source** is an object that points to a UFO file. It provides the outline geometry, kerning and font.info that we want to work with.
+
+```python
+s0 = SourceDescriptor()
+s0.path = "my/path/to/thin.ufo"
+s0.name = "master.thin"
+s0.location = dict(weight=0)
+doc.addSource(s0)
+```
+
+* You'll need to have at least 2 sources in your document, so go ahead and add another one. 
+* The **location** attribute is a dictionary with the designspace location for this master. 
+* The axis names in the location have to match one of the `axis.name` values you defined before.
+
+So go ahead and add another master:
+
+```python
+s1 = SourceDescriptor()
+s1.path = "my/path/to/bold.ufo"
+s1.name = "master.bold"
+s1.location = dict(weight=1000)
+doc.addSource(s1)
+```
+
+## Make an instance object
+
+An **instance** is description of a UFO that you want to generate with the designspace. For an instance you can define more things. If you want to generate UFO instances with MutatorMath then you can define different names and set flags for if you want to generate kerning and font info and so on. You can also set a path where to generate the instance.
+
+```python
+i0 = InstanceDescriptor()
+i0.familyName = "MyVariableFontPrototype"
+i0.styleName = "Medium"
+i0.postScriptFontName = "MyVariableFontPrototype-Medium"
+i0.path = os.path.join(root, "instances","MyVariableFontPrototype-Medium.ufo")
+i0.location = dict(weight=500)
+i0.kerning = True
+i0.info = True
+doc.addInstance(i0)
+```
+* The `path` attribute needs to be the full (real or intended) path for the instance. When the document is saved this path will written as relative to the path of the document.
+* instance paths should be on the same level as the document, or in a level below.
+
+# Saving
+
+```python
+path = "myprototype.designspace"
+doc.write(path)
+```
+
+# Generating?
+
+You can generate the UFO's with MutatorMath:
+
+```python
+from mutatorMath.ufo import build
+build("whatevs/myprototype.designspace")
+```
+
+Or you can use the file in making **variable font** with varlib.
+