def printEnumeration(indent, ns, parent):
node_list = parent.xpath('nx:item', namespaces=ns)
if len(node_list) == 0:
return ''
if len(node_list) == 1:
printf('%sObligatory value: ' % (indent))
else:
printf('%sAny of these values:' % (indent))
docs = OrderedDict()
for item in node_list:
name = item.get('value')
docs[name] = getDocLine(ns, item)
ENUMERATION_INLINE_LENGTH = 60
def show_as_typed_text(msg):
return '``%s``' % msg
oneliner = ' | '.join(map(show_as_typed_text, docs.keys()))
if (any(doc for doc in docs.values())
or len(oneliner) > ENUMERATION_INLINE_LENGTH):
# print one item per line
print('\n')
for name, doc in docs.items():
printf('%s * %s' % (indent, show_as_typed_text(name)))
if doc:
printf(': %s' % (doc))
print('\n')
else:
# print all items in one line
print(' %s' % (oneliner))
print('')
def printEnumeration( indent, ns, parent ):
node_list = parent.xpath('nx:item', namespaces=ns)
if len(node_list) == 0:
return ''
if len(node_list) == 1:
printf( '%sObligatory value: ' % ( indent ) )
else:
printf( '%sAny of these values:' % ( indent ) )
docs = OrderedDict()
for item in node_list:
name = item.get('value')
docs[name] = getDocLine(ns, item)
ENUMERATION_INLINE_LENGTH = 60
def show_as_typed_text(msg):
return '``%s``' % msg
oneliner = ' | '.join( map(show_as_typed_text, docs.keys()) )
if ( any( doc for doc in docs.values() ) or
len( oneliner ) > ENUMERATION_INLINE_LENGTH ):
# print one item per line
print('\n')
for name, doc in docs.items():
printf( '%s * %s' % ( indent, show_as_typed_text(name) ) )
if doc:
printf( ': %s' % ( doc ) )
print('\n')
else:
# print all items in one line
print(' %s' % ( oneliner ) )
print('')
def update(source_path, target_path):
'''
duplicate directory from source_path to target_path
:param source_path str: source directory (NeXus definitions dir)
:param target_path str: target directory is specified for build product
'''
# TODO: what about file items in target_path that are not in source_path?
source_path = os.path.abspath(source_path)
target_path = os.path.abspath(target_path)
qualify_inputs(source_path, target_path)
paths, files = get_source_items(REPLICATED_RESOURCES, source_path)
local_utilities.printf('source has %d directories and %d files\n', len(paths), len(files))
# create all the directories / subdirectories
for source in sorted(paths):
relative_name = source[len(source_path):].lstrip(os.sep)
target = standardize_name(target_path, relative_name)
if not os.path.exists(target):
local_utilities.printf('create directory %s\n', target)
os.mkdir(target, os.stat(source_path).st_mode)
# check if the files need to be updated
for source in sorted(files):
relative_name = source[len(source_path):].lstrip(os.sep)
target = standardize_name(target_path, relative_name)
if not identical(source, target):
local_utilities.printf('update file %s\n', target)
local_utilities.replicate(source, target)
def update(source_path, target_path):
'''
duplicate directory from source_path to target_path
:param source_path str: source directory (NeXus definitions dir)
:param target_path str: target directory is specified for build product
'''
# TODO: what about file items in target_path that are not in source_path?
source_path = os.path.abspath(source_path)
target_path = os.path.abspath(target_path)
qualify_inputs(source_path, target_path)
paths, files = get_source_items(REPLICATED_RESOURCES, source_path)
local_utilities.printf('source has %d directories and %d files\n',
len(paths), len(files))
# create all the directories / subdirectories
for source in sorted(paths):
relative_name = source[len(source_path):].lstrip(os.sep)
target = standardize_name(target_path, relative_name)
if not os.path.exists(target):
local_utilities.printf('create directory %s\n', target)
os.mkdir(target, os.stat(source_path).st_mode)
# check if the files need to be updated
for source in sorted(files):
relative_name = source[len(source_path):].lstrip(os.sep)
target = standardize_name(target_path, relative_name)
if not identical(source, target):
local_utilities.printf('update file %s\n', target)
local_utilities.replicate(source, target)
def print_rst_from_nxdl(nxdl_file):
'''
print restructured text from the named .nxdl.xml file
'''
global listing_category
# parse input file into tree
tree = lxml.etree.parse(nxdl_file)
# The following URL is outdated, but that doesn't matter;
# it won't be accessed; it's just an arbitrary namespace name.
# It only needs to match the xmlns attribute in the NXDL files.
NAMESPACE = 'http://definition.nexusformat.org/nxdl/3.1'
ns = {'nx': NAMESPACE}
root = tree.getroot()
name = root.get('name')
title = name
if len(name) < 2 or name[0:2] != 'NX':
raise Exception('Unexpected class name "%s"; does not start with NX' %
(name))
lexical_name = name[2:] # without padding 'NX', for indexing
# retrieve category from directory
#subdir = os.path.split(os.path.split(tree.docinfo.URL)[0])[1]
subdir = root.attrib["category"]
# TODO: check for consistency with root.get('category')
listing_category = {
'base': 'base class',
'application': 'application definition',
'contributed': 'contributed definition',
}[subdir]
use_application_defaults = listing_category in ('application definition',
'contributed definition')
# print ReST comments and section header
print('.. auto-generated by script %s from the NXDL source %s' %
(sys.argv[0], sys.argv[1]))
print('')
print('.. index::')
print(' ! %s (%s)' % (name, listing_category))
print(' ! %s (%s)' % (lexical_name, listing_category))
print(' see: %s (%s); %s' % (lexical_name, listing_category, name))
print('')
print('.. _%s:\n' % name)
print('=' * len(title))
print(title)
print('=' * len(title))
# print category, version, parent class
extends = root.get('extends')
if extends is None:
extends = 'none'
else:
extends = ':ref:`%s`' % extends
print('')
print('**Status**:\n')
print(' %s, extends %s, version %s' %
(listing_category.strip(), extends, root.get('version').strip()))
printIfDeprecated(ns, root, '')
# print official description of this class
print('')
print('**Description**:\n')
printDoc(INDENTATION_UNIT, ns, root, required=True)
# print symbol list
node_list = root.xpath('nx:symbols', namespaces=ns)
print('**Symbols**:\n')
if len(node_list) == 0:
print(' No symbol table\n')
elif len(node_list) > 1:
raise Exception('Invalid symbol table in ' % root.get('name'))
else:
printDoc(INDENTATION_UNIT, ns, node_list[0])
for node in node_list[0].xpath('nx:symbol', namespaces=ns):
doc = getDocLine(ns, node)
printf(' **%s**' % node.get('name'))
if doc:
printf(': %s' % doc)
print('\n')
# print group references
print('**Groups cited**:')
node_list = root.xpath('//nx:group', namespaces=ns)
groups = []
for node in node_list:
g = node.get('type')
if g.startswith('NX') and g not in groups:
groups.append(g)
if len(groups) == 0:
print(' none\n')
else:
out = [(':ref:`%s`' % g) for g in groups]
txt = ', '.join(sorted(out))
print(' %s\n' % (txt))
out = [('%s (base class); used in %s' % (g, listing_category))
for g in groups]
txt = ', '.join(out)
print('.. index:: %s\n' % (txt))
# TODO: change instances of \t to proper indentation
html_root = 'https://github.com/nexusformat/definitions/blob/master'
# print full tree
print('**Structure**:\n')
for subnode in root.xpath('nx:attribute', namespaces=ns):
optional = get_required_or_optional_text(subnode,
use_application_defaults)
printAttribute(ns, 'file', subnode, optional, INDENTATION_UNIT)
printFullTree(ns, root, name, INDENTATION_UNIT)
# print NXDL source location
subdir_map = {
'base': 'base_classes',
'application': 'applications',
'contributed': 'contributed_definitions',
}
print('**NXDL Source**:')
print(' %s/%s/%s.nxdl.xml' % (html_root, subdir_map[subdir], name))
def print_rst_from_nxdl(nxdl_file):
'''
print restructured text from the named .nxdl.xml file
'''
global listing_category
# parse input file into tree
tree = lxml.etree.parse(nxdl_file)
# The following URL is outdated, but that doesn't matter;
# it won't be accessed; it's just an arbitrary namespace name.
# It only needs to match the xmlns attribute in the NXDL files.
NAMESPACE = 'http://definition.nexusformat.org/nxdl/3.1'
ns = {'nx': NAMESPACE}
root = tree.getroot()
name = root.get('name')
title = name
if len(name)<2 or name[0:2]!='NX':
raise Exception( 'Unexpected class name "%s"; does not start with NX' %
( name ) )
lexical_name = name[2:] # without padding 'NX', for indexing
# retrieve category from directory
#subdir = os.path.split(os.path.split(tree.docinfo.URL)[0])[1]
subdir = root.attrib["category"]
# TODO: check for consistency with root.get('category')
listing_category = {
'base': 'base class',
'application': 'application definition',
'contributed': 'contributed definition',
}[subdir]
use_application_defaults = listing_category in (
'application definition',
'contributed definition')
# print ReST comments and section header
print( '.. auto-generated by script %s from the NXDL source %s' %
(sys.argv[0], sys.argv[1]) )
print('')
print( '.. index::' )
print( ' ! %s (%s)' % (name,listing_category) )
print( ' ! %s (%s)' % (lexical_name,listing_category) )
print( ' see: %s (%s); %s' %
(lexical_name,listing_category, name) )
print('')
print( '.. _%s:\n' % name )
print( '='*len(title) )
print( title )
print( '='*len(title) )
# print category, version, parent class
extends = root.get('extends')
if extends is None:
extends = 'none'
else:
extends = ':ref:`%s`' % extends
print('')
print( '**Status**:\n' )
print( ' %s, extends %s, version %s' %
( listing_category.strip(),
extends,
root.get('version').strip() ) )
printIfDeprecated(ns, root, '')
# print official description of this class
print('')
print( '**Description**:\n' )
printDoc(INDENTATION_UNIT, ns, root, required=True)
# print symbol list
node_list = root.xpath('nx:symbols', namespaces=ns)
print( '**Symbols**:\n' )
if len(node_list) == 0:
print( ' No symbol table\n' )
elif len(node_list) > 1:
raise Exception( 'Invalid symbol table in ' % root.get('name') )
else:
printDoc( INDENTATION_UNIT, ns, node_list[0] )
for node in node_list[0].xpath('nx:symbol', namespaces=ns):
doc = getDocLine(ns, node)
printf( ' **%s**' % node.get('name') )
if doc:
printf( ': %s' % doc )
print('\n')
# print group references
print( '**Groups cited**:' )
node_list = root.xpath('//nx:group', namespaces=ns)
groups = []
for node in node_list:
g = node.get('type')
if g.startswith('NX') and g not in groups:
groups.append(g)
if len(groups) == 0:
print( ' none\n' )
else:
out = [ (':ref:`%s`' % g) for g in groups ]
txt = ', '.join(sorted(out))
print( ' %s\n' % ( txt ) )
out = [ ('%s (base class); used in %s' % (g, listing_category)) for g in groups ]
txt = ', '.join(out)
print( '.. index:: %s\n' % ( txt ) )
# TODO: change instances of \t to proper indentation
html_root = 'https://github.com/nexusformat/definitions/blob/master'
# print full tree
print( '**Structure**:\n' )
for subnode in root.xpath('nx:attribute', namespaces=ns):
optional = get_required_or_optional_text(subnode, use_application_defaults)
printAttribute( ns, 'file', subnode, optional, INDENTATION_UNIT )
printFullTree(ns, root, name, INDENTATION_UNIT)
# print NXDL source location
subdir_map = {
'base': 'base_classes',
'application': 'applications',
'contributed': 'contributed_definitions',
}
print( '**NXDL Source**:' )
print( ' %s/%s/%s.nxdl.xml' % (
html_root, subdir_map[subdir], name) )