def library_include(parameters, config):
markdown_lines = []
policy_filename = parameters[0] + ".json"
policy_json = config.get(policy_filename)
html_name = config.get("context_current_html")
if policy_json == None:
policy_path = config["project_directory"] + "/_json/" + policy_filename
if not os.path.exists(policy_path):
print "cfdoc_syntaxmap:library_include: File does not exist: " + policy_path
return markdown_lines
policy_json = json.load(open(policy_path, 'r'))
config[policy_filename] = policy_json
# for all bundles and bodies...
for key in policy_json.keys():
element_list = policy_json[key]
current_type = None
for element in element_list:
namespace = element["namespace"]
if namespace == "default":
namespace = None
name = element["name"]
element_type = element.get("bundleType")
if element_type == None:
element_type = element.get("bodyType")
if element_type == None:
print "cfdoc_syntaxmap:library_include: element without type: " + name
continue
# start a new block for changed types
# Assumes that bundles and bodies are grouped by type in library.cf
if element_type != current_type:
current_type = element_type
markdown_lines.append("### " + current_type + " " + key + "\n")
markdown_lines.append("\n")
prototype = name
if namespace:
prototype = namespace + ":" + prototype
markdown_lines.append("#### " + prototype + "\n")
link_target = prototype + "()"
if not namespace:
link_target = parameters[0] + ":" + link_target
linkresolver.addLinkToMap("`" + prototype + "()`", link_target, html_name + "#" + prototype, config)
markdown_lines.append("\n")
code_lines = []
documentation_lines = []
documentation_dict = dict()
try:
source_path = config["project_directory"] + "/" + element["sourcePath"]
source_file = open(source_path, 'r')
sourceLine = element["sourceLine"]
sourceLines = source_file.readlines()
except:
print "cfdoc_syntaxmap:library_include: could not include code from " + name
if len(sourceLines):
# search up to include bundle/body declaration and comments in between
headerLines = list()
header_line = sourceLine - 1
while header_line:
line = sourceLines[header_line].lstrip()
header_line -= 1
headerLines.insert(0, line) # aka prepend
if key == "bundles" and line.find("bundle ") == 0:
break
if key == "bodies" and line.find("body ") == 0:
break
# scan comments for doxygen-style documentation
if len(headerLines):
current_tag = None
current_param = None
current_line = ""
for headerLine in headerLines:
if headerLine.find("#") != 0:
continue
headerLine = headerLine[1:].lstrip().rstrip()
if headerLine.find("@") == 0:
current_param = None
headerLine = headerLine[1:]
current_tag = headerLine[:headerLine.find(" ")]
headerLine = headerLine[len(current_tag) + 1:]
documentation_dict[current_tag] = ""
if current_tag == None:
continue
if current_tag == "param":
if current_param == None:
current_param = headerLine[:headerLine.find(" ")]
headerLine = headerLine[len(current_param) + 1:]
documentation_dict["param_" + current_param] = headerLine + "\n"
else:
documentation_dict["param_" + current_param] += headerLine + "\n"
else:
documentation_dict[current_tag] += headerLine + "\n"
brief = documentation_dict.get("brief", "")
if len(brief):
documentation_lines.append("**Description:** ")
documentation_lines.append(brief)
documentation_lines.append("\n")
return_doc = documentation_dict.get("return", "")
if len(return_doc):
documentation_lines.append("**Return value:** ")
documentation_lines.append(return_doc)
documentation_lines.append("\n")
code_lines.append("\n```cf3\n")
if len(headerLines):
code_lines.append(headerLines[0])
code_lines.append("{\n")
while sourceLine < len(sourceLines):
line = sourceLines[sourceLine]
code_lines.append(line)
# super-naive parser...
if line.find("}") == 0:
break
sourceLine += 1
code_lines.append("\n```\n")
arguments = element["arguments"]
argument_idx = 0
argument_lines = []
while argument_idx < len(arguments):
if argument_idx == 0:
prototype += "("
argument_lines.append("**Arguments:**\n\n")
argument = arguments[argument_idx]
prototype += argument
argument_line = "* `" + argument + "`"
# if we have already found documentation for this, use it
param_line = documentation_dict.get("param_" + argument)
if param_line != None:
argument_line += ": " + param_line
# find out where the argument is being used
elif key == "bundles":
for promise_type in element["promiseTypes"]:
promise_type_link = "`" + promise_type["name"] + "`"
for context in promise_type["contexts"]:
for promise in context["promises"]:
promiser = promise["promiser"]
if promiser.find("(" + argument + ")") != -1:
argument_line += ", used as promiser of type " + promise_type_link
else:
argument_line += resolveAttribute(promise["attributes"], argument)
if len(argument_line):
argument_line += " of " + promise_type_link + " promiser *" + promiser + "*"
elif key == "bodies":
for context in element["contexts"]:
argument_line += resolveAttribute(context["attributes"], argument)
argument_line += "\n"
argument_lines.append(argument_line)
argument_idx += 1
if argument_idx == len(arguments):
prototype += ")"
else:
prototype += ", "
markdown_lines.append("**Prototype:** `" + prototype + "`\n")
markdown_lines.append("\n")
if len(documentation_lines):
markdown_lines.append(documentation_lines)
markdown_lines.append("\n")
if len(argument_lines):
markdown_lines.append(argument_lines)
markdown_lines.append("\n")
if len(code_lines):
markdown_lines.append(code_lines)
markdown_lines.append("\n")
markdown_lines.append("\n")
if len(markdown_lines) == 0:
print "cfdoc_syntaxmap:library_include: Failure to include " + parameters[0]
return markdown_lines
def library_include(parameters, config):
markdown_lines = []
policy_filename = parameters[0] + ".json"
policy_json = config.get(policy_filename)
html_name = config.get("context_current_html")
qa.LogProcessStart(config, "library_include: %s" % policy_filename)
if policy_json == None:
policy_path = config["project_directory"] + "/_json/" + policy_filename
if not os.path.exists(policy_path):
qa.Log(config, "File does not exist: " + policy_path)
return markdown_lines
policy_json = json.load(open(policy_path, 'r'))
config[policy_filename] = policy_json
# for all bundles and bodies...
for key in policy_json.keys():
element_list = policy_json[key]
current_type = None
for element in element_list:
errorString = []
ignore = False
namespace = element["namespace"]
if namespace == "default":
namespace = None
name = element["name"]
element_type = element.get("bundleType")
if element_type == None:
element_type = element.get("bodyType")
if element_type == None:
qa.Log(config, "element without type: " + name)
continue
# start a new block for changed types
# Assumes that bundles and bodies are grouped by type in library.cf
print_type = False
if element_type != current_type:
current_type = element_type
print_type = True
prototype = name
if namespace:
prototype = namespace + ":" + prototype
title = prototype
link_target = prototype + "()"
if not namespace:
link_target = parameters[0] + ":" + link_target
linkresolver.addLinkToMap(prototype + "()", link_target, html_name + "#" + prototype, config)
code_lines = []
documentation_lines = []
documentation_dict = dict()
sourceLines = []
sourceLine = -1
try:
source_path = config["project_directory"] + "/" + element["sourcePath"]
source_path = os.path.normpath(source_path)
source_file = open(source_path, 'r')
sourceLine = element["line"] - 1 # zero-based indexing
sourceLines = source_file.readlines()[sourceLine:]
except:
qa.Log(config, "could not include code from " + name)
if len(sourceLines):
headerLines = list()
code_lines.append("\n```cf3\n")
code_lines.append(sourceLines[0])
del sourceLines[0]
in_code = False
for line in sourceLines:
if not in_code:
line = line.lstrip()
if line.find("{") == 0:
in_code = True
else:
headerLines.append(line)
if in_code:
code_lines.append(line)
# super-naive parser...
if line.find("}") == 0:
break
code_lines.append("\n```\n")
# scan comments for doxygen-style documentation
if len(headerLines):
current_tag = None
current_param = None
current_line = ""
for headerLine in headerLines:
if headerLine.find("#") != 0:
continue
headerLine = headerLine[1:].rstrip()
# strip single whitespace, but maintain indentation
if headerLine.find(" ") == 0:
headerLine = headerLine[1:]
if headerLine.lstrip().find("@") == 0:
current_param = None
headerLine = headerLine.lstrip()[1:]
current_tag = headerLine
tag_end = headerLine.find(" ")
if tag_end != -1:
current_tag = current_tag[:tag_end]
headerLine = headerLine[tag_end + 1:]
documentation_dict[current_tag] = ""
if current_tag == None:
continue
if current_tag == "ignore":
ignore = True
break
if current_tag == "param":
if current_param == None:
current_param = headerLine[:headerLine.find(" ")]
headerLine = headerLine[len(current_param) + 1:]
documentation_dict["param_" + current_param] = headerLine + "\n"
else:
documentation_dict["param_" + current_param] += headerLine + "\n"
else:
documentation_dict[current_tag] += headerLine + "\n"
brief = documentation_dict.get("brief", None)
if brief:
documentation_lines.append("**Description:** ")
documentation_lines.append(brief)
documentation_lines.append("\n")
else:
errorString.append("Missing description")
return_doc = documentation_dict.get("return", None)
if return_doc:
documentation_lines.append("**Return value:** ")
documentation_lines.append(return_doc)
documentation_lines.append("\n")
else: # no header lines
errorString.append("No documentation")
else: # no source lines
errorString.append("No source code or unable to read source code")
if ignore:
continue
arguments = element["arguments"]
argument_idx = 0
argument_lines = []
while argument_idx < len(arguments):
if argument_idx == 0:
prototype += "("
argument_lines.append("**Arguments:**\n\n")
argument = arguments[argument_idx]
prototype += argument
argument_line = "* ```" + argument + "```"
# if we have already found documentation for this, use it
param_line = documentation_dict.get("param_" + argument)
if param_line == None:
errorString.append("No documentation for parameter %s" % argument)
if param_line != None:
argument_line += ": " + param_line
# find out where the argument is being used
elif key == "bundles":
for promise_type in element["promiseTypes"]:
promise_type_link = "`" + promise_type["name"] + "`"
for context in promise_type["contexts"]:
for promise in context["promises"]:
promiser = promise["promiser"]
if promiser.find("(" + argument + ")") != -1:
argument_line += ", used as promiser of type " + promise_type_link
argument_line += "\n"
else:
argument_line += resolveAttribute(promise["attributes"], argument)
if len(argument_line):
argument_line += " of " + promise_type_link + " promiser *" + promiser + "*"
argument_line += "\n"
elif key == "bodies":
for context in element["contexts"]:
argument_line += resolveAttribute(context["attributes"], argument)
argument_line += "\n"
argument_lines.append(argument_line)
argument_idx += 1
if argument_idx == len(arguments):
prototype += ")"
else:
prototype += ", "
if print_type:
link_map = config["link_map"]
if ("`body %s`" % current_type) in link_map:
printable_type = "[%s]%s bodies" % (current_type, link_map["`body %s`" % current_type][0])
elif ("`bundle %s`" % current_type) in link_map:
printable_type = "[%s]%s bundles" % (current_type, link_map["`bundle %s`" % current_type][0])
elif ("`%s`" % current_type) in link_map:
printable_type = "[%s]%s %s" % (current_type, link_map["`%s`" % current_type][0], key)
elif key == "bundles":
printable_type = "%s [bundles][bundles]" % current_type
else:
printable_type = current_type
markdown_lines.append("### %s\n" % printable_type)
markdown_lines.append("\n")
markdown_lines.append("#### " + title + " ####\n")
markdown_lines.append("\n")
markdown_lines.append("**Prototype:** `" + prototype + "`\n")
markdown_lines.append("\n")
if len(documentation_lines):
markdown_lines.append(documentation_lines)
markdown_lines.append("\n")
if len(argument_lines):
markdown_lines.append(argument_lines)
markdown_lines.append("\n")
if len(code_lines):
markdown_lines.append("**Implementation:**\n")
markdown_lines.append("\n")
markdown_lines.append(code_lines)
markdown_lines.append("\n")
markdown_lines.append("\n")
if len(errorString):
locationString = "`in library `" + os.path.relpath(source_path) + "` (%d)" % sourceLine
qa.LogMissingDocumentation(config, prototype, errorString, locationString)
errorString = []
if len(markdown_lines) == 0:
qa.Log(config, "Failure to include " + parameters[0])
return markdown_lines
def library_include(parameters, config):
markdown_lines = []
policy_filename = parameters[0] + ".json"
policy_json = config.get(policy_filename)
html_name = config.get("context_current_html")
qa.LogProcessStart(config, "library_include: %s" % policy_filename)
if policy_json == None:
policy_path = config[
"project_directory"] + "/_generated/" + policy_filename
if not os.path.exists(policy_path):
qa.Log(config, "File does not exist: " + policy_path)
return markdown_lines
policy_json = json.load(open(policy_path, 'r'))
config[policy_filename] = policy_json
# for all bundles and bodies...
for key in policy_json.keys():
element_list = policy_json[key]
current_type = None
for element in element_list:
errorString = []
ignore = False
namespace = element["namespace"]
if namespace == "default":
namespace = None
name = element["name"]
element_type = element.get("bundleType")
if element_type == None:
element_type = element.get("bodyType")
if element_type == None:
qa.Log(config, "element without type: " + name)
continue
# start a new block for changed types
# Assumes that bundles and bodies are grouped by type in library.cf
print_type = False
if element_type != current_type:
current_type = element_type
print_type = True
prototype = name
if namespace:
prototype = namespace + ":" + prototype
title = prototype
link_target = prototype + "()"
if not namespace:
link_target = parameters[0] + ":" + link_target
linkresolver.addLinkToMap(prototype + "()", link_target,
html_name + "#" + prototype, config)
code_lines = []
documentation_lines = []
documentation_dict = dict()
sourceLines = []
sourceLine = -1
try:
source_path = element["sourcePath"]
source_path = os.path.normpath(source_path)
source_file = open(source_path, 'r')
sourceLine = element["line"] - 1 # zero-based indexing
sourceLines = source_file.readlines()[sourceLine:]
except:
qa.Log(
config,
"could not include code for element %s - check %s" %
(name, source_path))
if len(sourceLines):
headerLines = list()
code_lines.append("\n```cf3\n")
code_lines.append(sourceLines[0])
del sourceLines[0]
in_code = False
for line in sourceLines:
if not in_code:
line = line.lstrip()
if line.find("{") == 0:
in_code = True
else:
headerLines.append(line)
if in_code:
code_lines.append(line)
# super-naive parser...
if line.find("}\n") == 0:
break
code_lines.append("\n```\n")
# scan comments for doxygen-style documentation
if len(headerLines):
current_tag = None
current_param = None
current_line = ""
for headerLine in headerLines:
if headerLine.find("#") != 0:
continue
headerLine = headerLine[1:].rstrip()
# strip single whitespace, but maintain indentation
if headerLine.find(" ") == 0:
headerLine = headerLine[1:]
if headerLine.lstrip().find("@") == 0:
current_param = None
headerLine = headerLine.lstrip()[1:]
current_tag = headerLine
tag_end = headerLine.find(" ")
if tag_end != -1:
current_tag = current_tag[:tag_end]
headerLine = headerLine[tag_end + 1:]
documentation_dict[current_tag] = ""
if current_tag == None:
continue
if current_tag == "ignore":
ignore = True
break
if current_tag == "param":
if current_param == None:
current_param = headerLine[:headerLine.find(" "
)]
headerLine = headerLine[len(current_param) +
1:]
documentation_dict[
"param_" +
current_param] = headerLine + "\n"
else:
documentation_dict[
"param_" +
current_param] += headerLine + "\n"
else:
documentation_dict[
current_tag] += headerLine + "\n"
brief = documentation_dict.get("brief", None)
if brief:
documentation_lines.append("**Description:** ")
documentation_lines.append(brief)
documentation_lines.append("\n")
else:
errorString.append("Missing description")
return_doc = documentation_dict.get("return", None)
if return_doc:
documentation_lines.append("**Return value:** ")
documentation_lines.append(return_doc)
documentation_lines.append("\n")
else: # no header lines
errorString.append("No documentation")
else: # no source lines
errorString.append(
"No source code or unable to read source code")
if ignore:
continue
arguments = element["arguments"]
argument_idx = 0
argument_lines = []
while argument_idx < len(arguments):
if argument_idx == 0:
prototype += "("
argument_lines.append("**Arguments:**\n\n")
argument = arguments[argument_idx]
prototype += argument
argument_line = "* ```" + argument + "```"
# if we have already found documentation for this, use it
param_line = documentation_dict.get("param_" + argument)
if param_line == None:
errorString.append("No documentation for parameter %s" %
argument)
if param_line != None:
argument_line += ": " + param_line
# find out where the argument is being used
elif key == "bundles":
for promise_type in element["promiseTypes"]:
promise_type_link = "`" + promise_type["name"] + "`"
for context in promise_type["contexts"]:
for promise in context["promises"]:
promiser = promise["promiser"]
if promiser.find("(" + argument + ")") != -1:
argument_line += ", used as promiser of type " + promise_type_link
argument_line += "\n"
else:
argument_line += resolveAttribute(
promise["attributes"], argument)
if len(argument_line):
argument_line += " of " + promise_type_link + " promiser *" + promiser + "*"
argument_line += "\n"
elif key == "bodies":
for context in element["contexts"]:
argument_line += resolveAttribute(
context["attributes"], argument)
argument_line += "\n"
argument_lines.append(argument_line)
argument_idx += 1
if argument_idx == len(arguments):
prototype += ")"
else:
prototype += ", "
if print_type:
link_map = config["link_map"]
if ("`body %s`" % current_type) in link_map:
printable_type = "[%s]%s bodies" % (
current_type, link_map["`body %s`" % current_type][0])
elif ("`bundle %s`" % current_type) in link_map:
printable_type = "[%s]%s bundles" % (
current_type,
link_map["`bundle %s`" % current_type][0])
elif ("`%s`" % current_type) in link_map:
printable_type = "[%s]%s %s" % (
current_type, link_map["`%s`" % current_type][0], key)
elif key == "bundles":
printable_type = "%s [bundles][bundles]" % current_type
else:
printable_type = current_type
markdown_lines.append("### %s\n" % printable_type)
markdown_lines.append("\n")
markdown_lines.append("#### " + title + " ####\n")
markdown_lines.append("\n")
markdown_lines.append("**Prototype:** `" + prototype + "`\n")
markdown_lines.append("\n")
if len(documentation_lines):
markdown_lines.append(documentation_lines)
markdown_lines.append("\n")
if len(argument_lines):
markdown_lines.append(argument_lines)
markdown_lines.append("\n")
if len(code_lines):
markdown_lines.append("**Implementation:**\n")
markdown_lines.append("\n")
markdown_lines.append(code_lines)
markdown_lines.append("\n")
markdown_lines.append("\n")
if len(errorString):
locationString = "`in library `" + os.path.relpath(
source_path) + "` (%d)" % sourceLine
qa.LogMissingDocumentation(config, prototype, errorString,
locationString)
errorString = []
if len(markdown_lines) == 0:
qa.Log(config, "Failure to include " + parameters[0])
return markdown_lines