Merge pull request #592 from nexusformat/units_530

for #530: adds machine-readable unit strings

nxdlTypes.xsd

@@ -87,7 +87,8 @@
 	<xs:simpleType name="NX_ANGLE">
 		<xs:annotation>
 			<xs:documentation>
-				units of angle, example: m
+				units of angle
+				<xs:element name="example">m</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -105,7 +106,9 @@
 	<xs:simpleType name="NX_AREA">
 		<xs:annotation>
 			<xs:documentation>
-				units of area, example: m2 or barns
+				units of area
+				<xs:element name="example">m^2</xs:element>
+				<xs:element name="example">barns</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -114,7 +117,8 @@
 	<xs:simpleType name="NX_CROSS_SECTION">
 		<xs:annotation>
 			<xs:documentation>
-				units of area, example: barns (alias of NX_AREA)
+				units of area (alias of NX_AREA)
+				<xs:element name="example">barn</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:union memberTypes="nxdl:NX_AREA" />
@@ -123,7 +127,8 @@
 	<xs:simpleType name="NX_CHARGE">
 		<xs:annotation>
 			<xs:documentation>
-				units of electrical charge, example: c
+				units of electrical charge
+				<xs:element name="example">c</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -132,7 +137,8 @@
 	<xs:simpleType name="NX_CURRENT">
 		<xs:annotation>
 			<xs:documentation>
-				units of electrical current, example: A
+				units of electrical current
+				<xs:element name="example">A</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -141,9 +147,9 @@
 	<xs:simpleType name="NX_DIMENSIONLESS">
 		<xs:annotation>
 			<xs:documentation>
-				units for fields where the units cancel out, 
-				example: "" or mm/mm 
+				units for fields where the units cancel out
 				(NOTE: not the same as NX_UNITLESS)
+				<xs:element name="example">m/m</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -153,7 +159,8 @@
 		<xs:annotation>
 			<xs:documentation>
 				units of emittance (``length * angle``) of a 
-				radiation source, example: ``nm*rad``
+				radiation source
+				<xs:element name="example">nm*rad</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -162,7 +169,9 @@
 	<xs:simpleType name="NX_ENERGY">
 		<xs:annotation>
 			<xs:documentation>
-				units of energy, example: J or keV
+				units of energy
+				<xs:element name="example">J</xs:element>
+				<xs:element name="example">keV</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -171,7 +180,8 @@
 	<xs:simpleType name="NX_FLUX">
 		<xs:annotation>
 			<xs:documentation>
-				units of flux, example: s-1 cm-2
+				units of flux
+				<xs:element name="example">1/s/cm^2</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -180,7 +190,8 @@
 	<xs:simpleType name="NX_FREQUENCY">
 		<xs:annotation>
 			<xs:documentation>
-				units of frequency, example: Hz
+				units of frequency
+				<xs:element name="example">Hz</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -189,7 +200,8 @@
 	<xs:simpleType name="NX_LENGTH">
 		<xs:annotation>
 			<xs:documentation>
-				units of length, example: m
+				units of length
+				<xs:element name="example">m</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -198,7 +210,8 @@
 	<xs:simpleType name="NX_MASS">
 		<xs:annotation>
 			<xs:documentation>
-				units of length, example: g
+				units of mass
+				<xs:element name="example">g</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -207,7 +220,8 @@
 	<xs:simpleType name="NX_MASS_DENSITY">
 		<xs:annotation>
 			<xs:documentation>
-				units of mass density, example: g cm-3
+				units of mass density
+				<xs:element name="example">g/cm^3</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -216,7 +230,8 @@
 	<xs:simpleType name="NX_MOLECULAR_WEIGHT">
 		<xs:annotation>
 			<xs:documentation>
-				units of molecular weight, example: g mol-1
+				units of molecular weight
+				<xs:element name="example">g/mol</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -225,7 +240,8 @@
 	<xs:simpleType name="NX_PER_AREA">
 		<xs:annotation>
 			<xs:documentation>
-				units of length, example: m
+				units of 1/length^2
+				<xs:element name="example">1/m^2</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -234,7 +250,8 @@
 	<xs:simpleType name="NX_PER_LENGTH">
 		<xs:annotation>
 			<xs:documentation>
-				units of length, example: m
+				units of 1/length
+				<xs:element name="example">1/m</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -243,8 +260,9 @@
 	<xs:simpleType name="NX_PERIOD">
 		<xs:annotation>
 			<xs:documentation>
-				units of time, period of pulsed source, 
-				example: microseconds (alias to `NX_TIME`)
+				units of time, period of pulsed source 
+				(alias to `NX_TIME`)
+				<xs:element name="example">us</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="nxdl:NX_TIME" />
@@ -253,7 +271,8 @@
 	<xs:simpleType name="NX_POWER">
 		<xs:annotation>
 			<xs:documentation>
-				units of power, example: W
+				units of power
+				<xs:element name="example">W</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -262,7 +281,8 @@
 	<xs:simpleType name="NX_PRESSURE">
 		<xs:annotation>
 			<xs:documentation>
-				units of pressure, example: Pa
+				units of pressure
+				<xs:element name="example">Pa</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -280,7 +300,8 @@
 	<xs:simpleType name="NX_SCATTERING_LENGTH_DENSITY">
 		<xs:annotation>
 			<xs:documentation>
-				units of scattering length density, example: cm-2
+				units of scattering length density
+				<xs:element name="example">m/m^3</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<!-- isn't this an alias of NX_PER_AREA?  
@@ -292,7 +313,9 @@
 	<xs:simpleType name="NX_SOLID_ANGLE">
 		<xs:annotation>
 			<xs:documentation>
-				units of solid angle, example: sr | steradian
+				units of solid angle
+				<xs:element name="example">sr</xs:element>
+				<xs:element name="example">steradian</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -301,7 +324,8 @@
 	<xs:simpleType name="NX_TEMPERATURE">
 		<xs:annotation>
 			<xs:documentation>
-				units of temperature, example: K
+				units of temperature
+				<xs:element name="example">K</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -310,7 +334,8 @@
 	<xs:simpleType name="NX_TIME">
 		<xs:annotation>
 			<xs:documentation>
-				units of time, example: s
+				units of time
+				<xs:element name="example">s</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -319,8 +344,9 @@
 	<xs:simpleType name="NX_TIME_OF_FLIGHT">
 		<xs:annotation>
 			<xs:documentation>
-				units of (neutron) time of flight, 
-				example: s (alias to `NX_TIME`)
+				units of (neutron) time of flight
+				(alias to `NX_TIME`)
+				<xs:element name="example">s</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="nxdl:NX_TIME" />
@@ -366,7 +392,8 @@
 	<xs:simpleType name="NX_VOLTAGE">
 		<xs:annotation>
 			<xs:documentation>
-				units of voltage, example: V
+				units of voltage
+				<xs:element name="example">V</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -375,7 +402,8 @@
 	<xs:simpleType name="NX_VOLUME">
 		<xs:annotation>
 			<xs:documentation>
-				units of volume, example: m3
+				units of volume
+				<xs:element name="example">m3</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -384,7 +412,8 @@
 	<xs:simpleType name="NX_WAVELENGTH">
 		<xs:annotation>
 			<xs:documentation>
-				units of wavelength, example: angstrom
+				units of wavelength
+				<xs:element name="example">angstrom</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<xs:restriction base="xs:string" />
@@ -393,8 +422,9 @@
 	<xs:simpleType name="NX_WAVENUMBER">
 		<xs:annotation>
 			<xs:documentation>
-				units of wavenumber or Q, 
-				example: `angstrom-1` or `nm-1`
+				units of wavenumber or Q
+				<xs:element name="example">1/nm</xs:element>
+				<xs:element name="example">1/angstrom</xs:element>
 			</xs:documentation>
 		</xs:annotation>
 		<!-- isn't this an alias of NX_PER_LENGTH? -->

utils/dev_units2rst.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python
+
+'''
+Developers: use this code to develop and test nxdl2rst.py
+'''
+
+import sys
+from units2rst import worker
+
+
+sys.argv.append("../nxdlTypes.xsd")
+worker('anyUnitsAttr')

utils/units2rst.py

@@ -49,7 +49,15 @@ def worker(nodeMatchString, section = 'units'):
         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
+            examples = []
+            for example in words.iterchildren():
+                nm = example.attrib.get("name")
+                if nm is not None and nm == "example":
+                    examples.append("``"+example.text+"``")
+            a = words.text
+            if len(examples) > 0:
+                a = a.strip() + ", example(s): " + " | ".join(examples)
+            db[node_name] = a
 
 #             for item in node.xpath('xs:restriction//xs:enumeration', namespaces=ns):
 #                 key = '%s' % item.get('value')