def generate_all():
""" Scan for XML files in the src directory and call scons-proc.py
to generate the *.gen/*.mod files from it.
"""
flist = []
for path, dirs, files in os.walk('src'):
for f in files:
if f.endswith('.xml'):
fpath = os.path.join(path, f)
if SConsDoc.isSConsXml(fpath):
flist.append(fpath)
if flist:
# Does the destination folder exist
if not os.path.isdir(gen_folder):
try:
os.makedirs(gen_folder)
except:
print("Couldn't create destination folder %s! Exiting..." %
gen_folder)
return
# Call scons-proc.py
cp = subprocess.run([
sys.executable,
os.path.join('bin', 'scons-proc.py'), '-b',
argpair('builders'), '-f',
argpair('functions'), '-t',
argpair('tools'), '-v',
argpair('variables')
] + flist,
shell=False)
# No-op: scons-proc doesn't actually set an exit code at the moment.
if cp.returncode:
print("Generation failed", file=sys.stderr)
def generate_all():
""" Scan for XML files in the src directory and call scons-proc.py
to generate the *.gen/*.mod files from it.
"""
flist = []
for path, dirs, files in os.walk('src'):
for f in files:
if f.endswith('.xml'):
fpath = os.path.join(path, f)
if SConsDoc.isSConsXml(fpath):
flist.append(fpath)
if flist:
# Does the destination folder exist
if not os.path.isdir(gen_folder):
try:
os.makedirs(gen_folder)
except:
print("Couldn't create destination folder %s! Exiting..." % gen_folder)
return
# Call scons-proc.py
os.system('%s %s -b %s -f %s -t %s -v %s %s' %
(sys.executable, os.path.join('bin','scons-proc.py'),
argpair('builders'), argpair('functions'),
argpair('tools'), argpair('variables'), ' '.join(flist)))
def generate_all():
""" Scan for XML files in the src directory and call scons-proc.py
to generate the *.gen/*.mod files from it.
"""
flist = []
for path, dirs, files in os.walk('src'):
for f in files:
if f.endswith('.xml'):
fpath = os.path.join(path, f)
if SConsDoc.isSConsXml(fpath):
flist.append(fpath)
if flist:
# Does the destination folder exist
if not os.path.isdir(gen_folder):
try:
os.makedirs(gen_folder)
except:
print("Couldn't create destination folder %s! Exiting..." %
gen_folder)
return
# Call scons-proc.py
os.system('%s %s -b %s -f %s -t %s -v %s %s' %
(sys.executable, os.path.join('bin', 'scons-proc.py'),
argpair('builders'), argpair('functions'), argpair('tools'),
argpair('variables'), ' '.join(flist)))
def collectSConsExampleNames(fpath):
""" Return a set() of example names, used in the given file fpath.
"""
names = set()
suffixes = {}
failed_suffixes = False
# Create doctree
t = SConsDoc.SConsDocTree()
t.parseXmlFile(fpath)
# Parse it
for e in stf.findAll(t.root, "scons_example", SConsDoc.dbxid,
t.xpath_context, t.nsmap):
n = ''
if stf.hasAttribute(e, 'name'):
n = stf.getAttribute(e, 'name')
if n:
names.add(n)
if n not in suffixes:
suffixes[n] = []
else:
print("Error: Example in file '%s' is missing a name!" % fpath)
failed_suffixes = True
for o in stf.findAll(t.root, "scons_output", SConsDoc.dbxid,
t.xpath_context, t.nsmap):
n = ''
if stf.hasAttribute(o, 'example'):
n = stf.getAttribute(o, 'example')
else:
print("Error: scons_output in file '%s' is missing an example name!" % fpath)
failed_suffixes = True
if n not in suffixes:
print("Error: scons_output in file '%s' is referencing non-existent example '%s'!" % (fpath, n))
failed_suffixes = True
continue
s = ''
if stf.hasAttribute(o, 'suffix'):
s = stf.getAttribute(o, 'suffix')
else:
print("Error: scons_output in file '%s' (example '%s') is missing a suffix!" % (fpath, n))
failed_suffixes = True
if s not in suffixes[n]:
suffixes[n].append(s)
else:
print("Error: scons_output in file '%s' (example '%s') is using a duplicate suffix '%s'!" % (fpath, n, s))
failed_suffixes = True
return names, failed_suffixes
def readAllExampleInfos(dpath):
""" Scan for XML files in the given directory and
collect together all relevant infos (files/folders,
output commands) in a map, which gets returned.
"""
examples = {}
for path, dirs, files in os.walk(dpath):
for f in files:
if f.endswith('.xml'):
fpath = os.path.join(path, f)
if SConsDoc.isSConsXml(fpath):
readExampleInfos(fpath, examples)
return examples
def readAllExampleInfos(dpath):
""" Scan for XML files in the given directory and
collect together all relevant infos (files/folders,
output commands) in a map, which gets returned.
"""
examples = {}
for path, dirs, files in os.walk(dpath):
for f in files:
if f.endswith('.xml'):
fpath = os.path.join(path, f)
if SConsDoc.isSConsXml(fpath):
readExampleInfos(fpath, examples)
return examples
def generate_all():
"""Generate the entity files.
Scan for XML files in the SCons directory and call scons-proc.py
to generate the *.gen/*.mod files from it.
"""
flist = []
for path, dirs, files in os.walk('SCons'):
for f in files:
if f.endswith('.xml'):
fpath = os.path.join(path, f)
if SConsDoc.isSConsXml(fpath):
flist.append(fpath)
if flist:
# Does the destination folder exist
try:
os.makedirs(gen_folder, exist_ok=True)
except Exception:
print("Couldn't create destination folder %s! Exiting..." %
gen_folder,
file=sys.stdout)
return False
# Call scons-proc.py
cp = subprocess.run(
[
sys.executable,
os.path.join('bin', 'scons-proc.py'),
'-b',
argpair('builders'),
'-f',
argpair('functions'),
'-t',
argpair('tools'),
'-v',
argpair('variables'),
] + flist,
shell=False,
)
if cp.returncode:
print("Generation failed", file=sys.stderr)
return False
return True
def parse_docs(args, include_entities=True):
h = SConsDoc.SConsDocHandler()
for f in args:
if include_entities:
try:
h.parseXmlFile(f)
except:
sys.stderr.write("error in %s\n" % f)
raise
else:
content = open(f).read()
if content:
try:
h.parseContent(content, include_entities)
except:
sys.stderr.write("error in %s\n" % f)
raise
return h
def parse_docs(args, include_entities=True):
h = SConsDoc.SConsDocHandler()
for f in args:
if include_entities:
try:
h.parseXmlFile(f)
except:
sys.stderr.write("error in %s\n" % f)
raise
else:
# mode we read (text/bytes) has to match handling in SConsDoc
with open(f, 'r') as fp:
content = fp.read()
if content:
try:
h.parseContent(content, include_entities)
except:
sys.stderr.write("error in %s\n" % f)
raise
return h
def exampleNamesAreUnique(dpath):
""" Scan for XML files in the given directory and
check whether the scons_example names are unique.
"""
unique = True
allnames = set()
for path, dirs, files in os.walk(dpath):
for f in files:
if f.endswith('.xml'):
fpath = os.path.join(path, f)
if SConsDoc.isSConsXml(fpath):
names, failed_suffixes = collectSConsExampleNames(fpath)
if failed_suffixes:
unique = False
i = allnames.intersection(names)
if i:
print "Not unique in %s are: %s" % (fpath, ', '.join(i))
unique = False
allnames |= names
return unique
def parse_docs(args, include_entities=True):
h = SConsDoc.SConsDocHandler()
for f in args:
if include_entities:
try:
h.parseXmlFile(f)
except Exception as e:
print("error parsing %s\n" % f, file=sys.stderr)
print(str(e), file=sys.stderr)
sys.exit(1)
else:
# mode we read (text/bytes) has to match handling in SConsDoc
with open(f, 'r') as fp:
content = fp.read()
if content:
try:
h.parseContent(content, include_entities)
except Exception as e:
print("error parsing %s\n" % f, file=sys.stderr)
print(str(e), file=sys.stderr)
sys.exit(1)
return h
def exampleNamesAreUnique(dpath):
""" Scan for XML files in the given directory and
check whether the scons_example names are unique.
"""
unique = True
allnames = set()
for path, dirs, files in os.walk(dpath):
for f in files:
if f.endswith('.xml'):
fpath = os.path.join(path, f)
if SConsDoc.isSConsXml(fpath):
names, failed_suffixes = collectSConsExampleNames(fpath)
if failed_suffixes:
unique = False
i = allnames.intersection(names)
if i:
print("Not unique in %s are: %s" % (fpath, ', '.join(i)))
unique = False
allnames |= names
return unique
g = processor_class([Variable(v) for v in sorted(h.cvars.values())],
env_signatures=False)
write_func(g, variablesfiles)
processor_class = SCons_XML
# Step 1: Creating entity files for builders, functions,...
print("Generating entity files...")
h = parse_docs(args, include_entities=False)
write_output_files(h, buildersfiles, functionsfiles, toolsfiles,
variablesfiles, SCons_XML.write_mod)
# Step 2: Validating all input files
print("Validating files against SCons XSD...")
if SConsDoc.validate_all_xml(['SCons']):
print("OK")
else:
print("Validation failed! Please correct the errors above and try again.")
# Step 3: Creating actual documentation snippets, using the
# fully resolved and updated entities from the *.mod files.
print("Updating documentation for builders, tools and functions...")
h = parse_docs(args, include_entities=True)
write_output_files(h, buildersfiles, functionsfiles, toolsfiles,
variablesfiles, SCons_XML.write)
print("Done")
# Local Variables:
# tab-width:4
# indent-tabs-mode:nil
xml_preamble = """\
<?xml version="1.0"?>
<scons_doc>
"""
xml_postamble = """\
</scons_doc>
"""
for f in args:
_, ext = os.path.splitext(f)
if ext == '.py':
dir, _ = os.path.split(f)
if dir:
sys.path = [dir] + base_sys_path
module = SConsDoc.importfile(f)
h.set_file_info(f, len(xml_preamble.split('\n')))
try:
content = module.__scons_doc__
except AttributeError:
content = None
else:
del module.__scons_doc__
else:
h.set_file_info(f, len(xml_preamble.split('\n')))
content = open(f).read()
if content:
content = content.replace('&', '&')
input = xml_preamble + content + xml_postamble
try:
saxparser.parse(StringIO.StringIO(input))
variablesfiles = None
for o, a in opts:
if o in ['-b', '--builders']:
buildersfiles = a
elif o in ['-h', '--help']:
sys.stdout.write(helpstr)
sys.exit(0)
elif o in ['--man', '--sgml']:
output_type = o
elif o in ['-t', '--tools']:
toolsfiles = a
elif o in ['-v', '--variables']:
variablesfiles = a
h = SConsDoc.SConsDocHandler()
saxparser = xml.sax.make_parser()
saxparser.setContentHandler(h)
saxparser.setErrorHandler(h)
xml_preamble = """\
<?xml version="1.0"?>
<scons_doc>
"""
xml_postamble = """\
</scons_doc>
"""
for f in args:
_, ext = os.path.splitext(f)
def readExampleInfos(fpath, examples):
""" Add the example infos for the file fpath to the
global dictionary examples.
"""
# Create doctree
t = SConsDoc.SConsDocTree()
t.parseXmlFile(fpath)
# Parse scons_examples
for e in stf.findAll(t.root, "scons_example", SConsDoc.dbxid,
t.xpath_context, t.nsmap):
n = ''
if stf.hasAttribute(e, 'name'):
n = stf.getAttribute(e, 'name')
if n and n not in examples:
i = ExampleInfo()
i.name = n
examples[n] = i
# Parse file and directory entries
for f in stf.findAll(e, "file", SConsDoc.dbxid,
t.xpath_context, t.nsmap):
fi = ExampleFile()
if stf.hasAttribute(f, 'name'):
fi.name = stf.getAttribute(f, 'name')
if stf.hasAttribute(f, 'chmod'):
fi.chmod = stf.getAttribute(f, 'chmod')
fi.content = stf.getText(f)
examples[n].files.append(fi)
for d in stf.findAll(e, "directory", SConsDoc.dbxid,
t.xpath_context, t.nsmap):
di = ExampleFolder()
if stf.hasAttribute(d, 'name'):
di.name = stf.getAttribute(d, 'name')
if stf.hasAttribute(d, 'chmod'):
di.chmod = stf.getAttribute(d, 'chmod')
examples[n].folders.append(di)
# Parse scons_example_files
for f in stf.findAll(t.root, "scons_example_file", SConsDoc.dbxid,
t.xpath_context, t.nsmap):
if stf.hasAttribute(f, 'example'):
e = stf.getAttribute(f, 'example')
else:
continue
fi = ExampleFile(FT_FILEREF)
if stf.hasAttribute(f, 'name'):
fi.name = stf.getAttribute(f, 'name')
if stf.hasAttribute(f, 'chmod'):
fi.chmod = stf.getAttribute(f, 'chmod')
fi.content = stf.getText(f)
examples[e].files.append(fi)
# Parse scons_output
for o in stf.findAll(t.root, "scons_output", SConsDoc.dbxid,
t.xpath_context, t.nsmap):
if stf.hasAttribute(o, 'example'):
n = stf.getAttribute(o, 'example')
else:
continue
eout = ExampleOutput()
if stf.hasAttribute(o, 'name'):
eout.name = stf.getAttribute(o, 'name')
if stf.hasAttribute(o, 'tools'):
eout.tools = stf.getAttribute(o, 'tools')
if stf.hasAttribute(o, 'os'):
eout.os = stf.getAttribute(o, 'os')
if stf.hasAttribute(o, 'suffix'):
eout.suffix = stf.getAttribute(o, 'suffix')
for c in stf.findAll(o, "scons_output_command", SConsDoc.dbxid,
t.xpath_context, t.nsmap):
oc = ExampleCommand()
if stf.hasAttribute(c, 'edit'):
oc.edit = stf.getAttribute(c, 'edit')
if stf.hasAttribute(c, 'environment'):
oc.environment = stf.getAttribute(c, 'environment')
if stf.hasAttribute(c, 'output'):
oc.output = stf.getAttribute(c, 'output')
if stf.hasAttribute(c, 'cmd'):
oc.cmd = stf.getAttribute(c, 'cmd')
else:
oc.cmd = stf.getText(c)
eout.commands.append(oc)
examples[n].outputs.append(eout)
if variablesfiles:
g = processor_class([ Variable(v) for v in sorted(h.cvars.values()) ],
env_signatures=False)
write_func(g, variablesfiles)
processor_class = SCons_XML
# Step 1: Creating entity files for builders, functions,...
print "Generating entity files..."
h = parse_docs(args, False)
write_output_files(h, buildersfiles, functionsfiles, toolsfiles,
variablesfiles, SCons_XML.write_mod)
# Step 2: Validating all input files
print "Validating files against SCons XSD..."
if SConsDoc.validate_all_xml(['src']):
print "OK"
else:
print "Validation failed! Please correct the errors above and try again."
# Step 3: Creating actual documentation snippets, using the
# fully resolved and updated entities from the *.mod files.
print "Updating documentation for builders, tools and functions..."
h = parse_docs(args, True)
write_output_files(h, buildersfiles, functionsfiles, toolsfiles,
variablesfiles, SCons_XML.write)
print "Done"
# Local Variables:
# tab-width:4
# indent-tabs-mode:nil
#!/usr/bin/env python
#
# Searches through the whole source tree and validates all
# documentation files against our own XSD in docs/xsd.
#
import sys, os
import SConsDoc
if __name__ == "__main__":
if len(sys.argv) > 1:
if SConsDoc.validate_all_xml((sys.argv[1], )):
print "OK"
else:
print "Validation failed! Please correct the errors above and try again."
else:
if SConsDoc.validate_all_xml([
'src',
os.path.join('doc', 'design'),
os.path.join('doc', 'developer'),
os.path.join('doc', 'man'),
os.path.join('doc', 'python10'),
os.path.join('doc', 'reference'),
os.path.join('doc', 'user')
]):
print "OK"
else:
print "Validation failed! Please correct the errors above and try again."
sys.exit(1)
#!/usr/bin/env python
#
# Searches through the whole source tree and validates all
# documentation files against our own XSD in docs/xsd.
#
import sys,os
import SConsDoc
if __name__ == "__main__":
if len(sys.argv)>1:
if SConsDoc.validate_all_xml((sys.argv[1],)):
print "OK"
else:
print "Validation failed! Please correct the errors above and try again."
else:
if SConsDoc.validate_all_xml(['src',
os.path.join('doc','design'),
os.path.join('doc','developer'),
os.path.join('doc','man'),
os.path.join('doc','python10'),
os.path.join('doc','reference'),
os.path.join('doc','user')
]):
print "OK"
else:
print "Validation failed! Please correct the errors above and try again."
g = processor_class([Variable(v) for v in sorted(h.cvars.values())],
env_signatures=False)
write_func(g, variablesfiles)
processor_class = SCons_XML
# Step 1: Creating entity files for builders, functions,...
print "Generating entity files..."
h = parse_docs(args, False)
write_output_files(h, buildersfiles, functionsfiles, toolsfiles,
variablesfiles, SCons_XML.write_mod)
# Step 2: Validating all input files
print "Validating files against SCons XSD..."
if SConsDoc.validate_all_xml(['src']):
print "OK"
else:
print "Validation failed! Please correct the errors above and try again."
# Step 3: Creating actual documentation snippets, using the
# fully resolved and updated entities from the *.mod files.
print "Updating documentation for builders, tools and functions..."
h = parse_docs(args, True)
write_output_files(h, buildersfiles, functionsfiles, toolsfiles,
variablesfiles, SCons_XML.write)
print "Done"
# Local Variables:
# tab-width:4
# indent-tabs-mode:nil
