refs #555 : docs build with units described

nxdlTypes.xsd

@@ -65,6 +65,7 @@
 			nxdl:NX_MOLECULAR_WEIGHT
 			nxdl:NX_PER_AREA
 			nxdl:NX_PER_LENGTH
+			nxdl:NX_PERIOD
 			nxdl:NX_POWER 
 			nxdl:NX_PRESSURE
 			nxdl:NX_PULSES
@@ -243,7 +244,7 @@
 		<xs:annotation>
 			<xs:documentation>
 				units of time, period of pulsed source, 
-				example: microseconds (alias to NX_TIME)
+				example: microseconds (alias to `NX_TIME`)
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="nxdl:NX_TIME" />
@@ -270,7 +271,7 @@
 	<xs:simpleType name="NX_PULSES">
 		<xs:annotation>
 			<xs:documentation>
-				units of clock pulses (alias to NX_NUMBER)
+				units of clock pulses (alias to `NX_NUMBER`)
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="nxdl:NX_NUMBER" />
@@ -319,7 +320,7 @@
 		<xs:annotation>
 			<xs:documentation>
 				units of (neutron) time of flight, 
-				example: s (alias to NX_TIME)
+				example: s (alias to `NX_TIME`)
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="nxdl:NX_TIME" />

utils/types2rst.py

@@ -8,11 +8,55 @@
 '''
 
 
-import units2rst
+import os, sys
+import lxml.etree
+
+
+def worker(nodeMatchString, section = 'units'):
+    if len(sys.argv) != 2:
+        print("usage: %s nxdlTypes.xsd" % sys.argv[0])
+        exit()
+    NXDL_TYPES_FILE = sys.argv[1]
+    if not os.path.exists(NXDL_TYPES_FILE):
+        print("Cannot find %s" % NXDL_TYPES_FILE)
+        exit()
+
+    tree = lxml.etree.parse(NXDL_TYPES_FILE)
+
+    output = ['.. auto-generated by %s -- DO NOT EDIT' % sys.argv[0]]
+    output.append('')
+
+    labels = ('term', 'description')
+    output.append('.. nodeMatchString : %s' % nodeMatchString)
+    output.append('')
+    db = {}
+
+    NAMESPACE = 'http://www.w3.org/2001/XMLSchema'
+    ns = {'xs': NAMESPACE}
+    root = tree.xpath('//xs:schema', namespaces=ns)[0]
+    s = '//xs:simpleType'
+    for node in tree.xpath("//xs:simpleType", namespaces=ns):
+        if node.get('name') == nodeMatchString:
+            for item in node.xpath('xs:restriction//xs:enumeration', namespaces=ns):
+                key = '%s' % item.get('value')
+                words = item.xpath('xs:annotation/xs:documentation', namespaces=ns)[0]
+                db[key] = words.text
+
+    print('\n'.join(output))
+
+    # this list is too long to make this a table in latex
+    # for two columns, a Sphinx fieldlist will do just as well
+    for key in sorted(db):
+        print('.. index:: ! %s (%s type)\n' % (key, section))       # index entry
+        print('.. _%s:\n' % key)       # cross-reference point
+        print(':%s:' % key)
+        for line in db[key].splitlines():
+            print('    %s' % line)
+        print('')
 
 
 if __name__ == '__main__':
-    units2rst.worker('NAPI', section = 'data')
+    worker('NAPI', section = 'data')
 
 
 # NeXus - Neutron and X-ray Common Data Format

utils/units2rst.py

@@ -23,7 +23,7 @@ def worker(nodeMatchString, section = 'units'):
 
     tree = lxml.etree.parse(NXDL_TYPES_FILE)
 
-    output = ['.. auto-generated -- DO NOT EDIT']
+    output = ['.. auto-generated by %s -- DO NOT EDIT' % sys.argv[0]]
     output.append('')
 
     labels = ('term', 'description')
@@ -35,12 +35,26 @@ def worker(nodeMatchString, section = 'units'):
     ns = {'xs': NAMESPACE}
     root = tree.xpath('//xs:schema', namespaces=ns)[0]
     s = '//xs:simpleType'
-    for node in tree.xpath("//xs:simpleType", namespaces=ns):
+    node_list = tree.xpath("//xs:simpleType", namespaces=ns)
+
+    # get the names of all the types of units
+    members = []
+    for node in node_list:
         if node.get('name') == nodeMatchString:
-            for item in node.xpath('xs:restriction//xs:enumeration', namespaces=ns):
-                key = '%s' % item.get('value')
-                words = item.xpath('xs:annotation/xs:documentation', namespaces=ns)[0]
-                db[key] = words.text
+            union = node.xpath('xs:union', namespaces=ns)
+            members = union[0].get('memberTypes', '').split()
+
+    # get the definition of each type of units
+    for node in node_list:
+        node_name = node.get('name')
+        if 'nxdl:' + node_name in members:
+            words = node.xpath('xs:annotation/xs:documentation', namespaces=ns)[0]
+            db[node_name] = words.text
+
+#             for item in node.xpath('xs:restriction//xs:enumeration', namespaces=ns):
+#                 key = '%s' % item.get('value')
+#                 words = item.xpath('xs:annotation/xs:documentation', namespaces=ns)[0]
+#                 db[key] = words.text
 
     print('\n'.join(output))
 
@@ -56,6 +70,7 @@ def worker(nodeMatchString, section = 'units'):
 
 
 if __name__ == '__main__':
+    #sys.argv.append('../nxdlTypes.xsd')  # FIXME: developer only -- remove for production!!!
     worker('anyUnitsAttr')