forked from Imagelibrary/seL4
330 lines
9.7 KiB
Python
Executable File
330 lines
9.7 KiB
Python
Executable File
#!/usr/bin/env python
|
|
#
|
|
# Copyright 2017, Data61
|
|
# Commonwealth Scientific and Industrial Research Organisation (CSIRO)
|
|
# ABN 41 687 119 230.
|
|
#
|
|
# This software may be distributed and modified according to the terms of
|
|
# the BSD 2-Clause license. Note that NO WARRANTY is provided.
|
|
# See "LICENSE_BSD2.txt" for details.
|
|
#
|
|
# @TAG(DATA61_BSD)
|
|
#
|
|
|
|
"""
|
|
Script for generating latex from doxygen-generated xml files.
|
|
The generatetd latex files are compatible with the seL4 manual.
|
|
"""
|
|
import argparse
|
|
import sys
|
|
import os
|
|
import re
|
|
from bs4 import BeautifulSoup
|
|
import six
|
|
|
|
# Dict mapping characters to their escape sequence in latex
|
|
LATEX_ESCAPE_PATTERNS = {
|
|
"_": "\\_",
|
|
}
|
|
LATEX_ESCAPE_REGEX = re.compile('|'.join(LATEX_ESCAPE_PATTERNS.keys()))
|
|
|
|
def default_return_doc(ret_type):
|
|
"""
|
|
Returns the latex doc for the return value of a function
|
|
implied by its return type
|
|
"""
|
|
|
|
if ret_type == "void":
|
|
return "\\noret"
|
|
|
|
return ""
|
|
|
|
def latex_escape(string):
|
|
"""
|
|
Return a string with latex special characters escaped
|
|
"""
|
|
|
|
return LATEX_ESCAPE_REGEX.sub(lambda p: LATEX_ESCAPE_PATTERNS[p.group()], string)
|
|
|
|
def get_text(soup, escape=True):
|
|
"""
|
|
Return a string containing a concatenation of a nodes text node
|
|
children, recursing into non-text nodes or escaping latex if
|
|
necessary.
|
|
"""
|
|
|
|
if isinstance(soup, str):
|
|
string = soup
|
|
elif isinstance(soup, six.string_types):
|
|
string = str(soup)
|
|
elif soup.string:
|
|
string = str(soup.string)
|
|
else:
|
|
string = soup.get_text()
|
|
|
|
if string is not None:
|
|
if escape:
|
|
return latex_escape(string)
|
|
else:
|
|
return string
|
|
|
|
def ref_tex(refid, ref_dict):
|
|
"""Lookup refid in ref_dict and output the latex for an apifunc ref"""
|
|
ref = ref_dict[refid]
|
|
return "\\apifunc{%(name)s}{%(label)s}" % ref
|
|
|
|
def ref_to_tex(para, ref_dict):
|
|
"""Convert a reference by id to a latex command by looking up refid in para"""
|
|
if len(ref_dict) > 0:
|
|
return ref_tex(para["refid"], ref_dict)
|
|
return ""
|
|
|
|
def nref_to_tex(para, ref_dict):
|
|
"""Convert a reference by name to a latex command by looking up refid in para"""
|
|
if len(ref_dict) > 0:
|
|
return ref_tex(para["name"], ref_dict)
|
|
return ""
|
|
|
|
def parse_list(para, ref_dict, tag):
|
|
"""Parse an ordered list element"""
|
|
output = '\\begin{%s}\n' % tag
|
|
for item in para.contents:
|
|
output += parse_para(item, ref_dict)
|
|
output += '\\end{%s}\n' % tag
|
|
return output
|
|
|
|
def parse_ordered_list(para, ref_dict):
|
|
"""orderedlist --> enumerate"""
|
|
return parse_list(para, ref_dict, 'enumerate')
|
|
|
|
def parse_itemized_list(para, ref_dict):
|
|
"""itemizedlist --> itemize"""
|
|
return parse_list(para, ref_dict, 'itemize')
|
|
|
|
def parse_recurse(para, ref_dict):
|
|
"""Recursively parse a para element"""
|
|
# recurse on the contents
|
|
output = ""
|
|
for item in para.contents:
|
|
output += parse_para(item, ref_dict)
|
|
return output
|
|
|
|
# table of translations of xml children of 'para' elements
|
|
PARSE_TABLE = {
|
|
'para' : parse_recurse,
|
|
'computeroutput': lambda p, r: '\\texttt{%s}' % get_text(p),
|
|
'texttt' : lambda p, r: '\\texttt{%s}' % get_text(p['text']),
|
|
'ref' : ref_to_tex,
|
|
'nameref' : nref_to_tex,
|
|
'shortref' : lambda p, r: "\\ref{sec:%s}" % p['sec'],
|
|
'obj' : lambda p, r: "\\obj{%s}" % p['name'],
|
|
'errorenumdesc' : lambda p, r: "\\errorenumdesc",
|
|
'orderedlist' : parse_ordered_list,
|
|
'listitem' : lambda p, r: "\\item " + parse_para(p.para, r) + "\n",
|
|
'itemizedlist' : parse_itemized_list,
|
|
'autoref' : lambda p, r: "\\autoref{%s}" % p['label'],
|
|
}
|
|
|
|
def parse_para(para_node, ref_dict={}):
|
|
"""
|
|
Parse a paragraph node, handling special doxygen node types
|
|
that may appear inside a paragraph. Unhandled cases are
|
|
not parsed and result in an empty string.
|
|
"""
|
|
if para_node.name is None:
|
|
return get_text(para_node, escape=True)
|
|
elif para_node.name in PARSE_TABLE:
|
|
return PARSE_TABLE[para_node.name](para_node, ref_dict)
|
|
else:
|
|
return ""
|
|
|
|
def parse_brief(parent):
|
|
"""
|
|
Parse the "brief description" section of a doxygen member.
|
|
"""
|
|
para_nodes = parent.find('briefdescription').find_all('para')
|
|
return "\n\n".join([parse_para(n) for n in para_nodes])
|
|
|
|
def parse_detailed_desc(parent, ref_dict):
|
|
"""
|
|
Parse the "detailed description" section of a doxygen member.
|
|
"""
|
|
# parse the function parameters
|
|
params = {}
|
|
param_order = []
|
|
types_iter = iter(parent.find_all('type'))
|
|
names = parent.find_all('declname')
|
|
|
|
# the first type is the return type
|
|
ret_type = six.next(types_iter)
|
|
|
|
# the rest are parameters
|
|
for n in names:
|
|
param_type = six.next(types_iter).text
|
|
if param_type == "void":
|
|
continue
|
|
params[str(n.text)] = {"type": param_type}
|
|
param_order.append(str(n.text))
|
|
|
|
param_items = parent.find_all("parameteritem")
|
|
for param_item in param_items:
|
|
param_name_node = param_item.find("parametername")
|
|
param_desc_node = param_item.find("parameterdescription")
|
|
|
|
param_name = get_text(param_name_node, escape=False)
|
|
param_desc = parse_para(param_desc_node.find('para'), ref_dict)
|
|
|
|
params[param_name]["desc"] = param_desc
|
|
|
|
if len(params) == 0:
|
|
params_str = "\\param{void}{}{}"
|
|
else:
|
|
params_str = ""
|
|
for param_name in param_order:
|
|
param_info = params[param_name]
|
|
params_str += "\\param{%(type)s}{%(name)s}{%(desc)s}\n" % {
|
|
"type": get_text(param_info["type"]),
|
|
"name": get_text(param_name),
|
|
"desc": todo_if_empty(param_info.get("desc", "").strip()),
|
|
}
|
|
|
|
|
|
details = ""
|
|
for n in parent.detaileddescription.find_all('para', recursive=False):
|
|
if not n.parameterlist:
|
|
details += parse_para(n, ref_dict)
|
|
details += "\n\n"
|
|
|
|
ret_str = get_text(ret_type, escape=False)
|
|
ret = default_return_doc(ret_str.split()[-1])
|
|
simplesects = parent.find_all("simplesect")
|
|
for n in simplesects:
|
|
if n['kind'] == "return":
|
|
ret = parse_para(n.find('para'), ref_dict)
|
|
break
|
|
return (todo_if_empty(details.strip()), params_str, todo_if_empty(ret.strip()))
|
|
|
|
def parse_prototype(parent):
|
|
"""
|
|
Extract a function prototype from a doxygen member.
|
|
"""
|
|
|
|
inline = parent["inline"] == "yes"
|
|
static = parent["static"] == "yes"
|
|
ret_type = get_text(parent.find("type"))
|
|
name = get_text(parent.find("name"))
|
|
|
|
output = "%s %s" % (ret_type, name)
|
|
if inline:
|
|
output = "inline " + output
|
|
if static:
|
|
output = "static " + output
|
|
|
|
return output
|
|
|
|
def build_ref_dict(soup):
|
|
"""
|
|
Return a dict mapping reference ids and reference names
|
|
to details about the referee.
|
|
"""
|
|
|
|
ret = {}
|
|
for member in soup.find_all("memberdef"):
|
|
name = str(member.find('name').string)
|
|
label = member.manual['label']
|
|
ref_id = member['id']
|
|
data = {
|
|
"name": latex_escape(name),
|
|
"label": label,
|
|
"ref": ref_id,
|
|
}
|
|
|
|
ret[ref_id] = data
|
|
ret[name] = data
|
|
|
|
return ret
|
|
|
|
def todo_if_empty(s):
|
|
"""
|
|
Returns its argument if its argument is non-none and non-empty,
|
|
otherwise returns "\\todo"
|
|
"""
|
|
return s if s else "\\todo"
|
|
|
|
def generate_general_syscall_doc(input_file_name, level):
|
|
"""
|
|
Takes a path to a file containing doxygen-generated xml,
|
|
and return a string containing latex suitable for inclusion
|
|
in the sel4 manual.
|
|
"""
|
|
|
|
with open(input_file_name, "r") as f:
|
|
output = ""
|
|
soup = BeautifulSoup(f, "lxml")
|
|
ref_dict = build_ref_dict(soup)
|
|
elements = soup.find_all("memberdef")
|
|
summary = soup.find('compounddef')
|
|
# parse any top level descriptions
|
|
for ddesc in summary.find_all('detaileddescription', recursive=False):
|
|
if ddesc.para:
|
|
output += parse_para(ddesc.para)
|
|
|
|
# parse all of the function definitions
|
|
if len(elements) == 0:
|
|
return "No methods."
|
|
|
|
for member in elements:
|
|
manual_node = member.manual
|
|
details, params, ret = parse_detailed_desc(member, ref_dict)
|
|
output += """
|
|
\\apidoc
|
|
[{%(level)s}]
|
|
{%(label)s}
|
|
{%(name)s}
|
|
{%(brief)s}
|
|
{%(prototype)s}
|
|
{%(params)s}
|
|
{%(ret)s}
|
|
{%(details)s}
|
|
""" % {
|
|
"level": level,
|
|
"label": manual_node["label"],
|
|
"name": latex_escape(manual_node["name"]),
|
|
"brief": todo_if_empty(parse_brief(member)),
|
|
"prototype": parse_prototype(member),
|
|
"params": params,
|
|
"ret": ret,
|
|
"details": details,
|
|
}
|
|
|
|
return output
|
|
|
|
def process_args():
|
|
"""Process script arguments"""
|
|
parser = argparse.ArgumentParser()
|
|
|
|
parser.add_argument("-i", "--input", dest="input", type=str,
|
|
help="File containing doxygen-generated xml.")
|
|
parser.add_argument("-o", "--output", dest="output", type=str,
|
|
help="Output latex file.")
|
|
|
|
parser.add_argument("-l", "--level", choices=["subsection", "subsubsection"],
|
|
help="LaTeX section level for each method")
|
|
|
|
return parser
|
|
|
|
def main():
|
|
"""Convert doxygen xml into a seL4 API LaTeX manual format"""
|
|
args = process_args().parse_args()
|
|
|
|
if not os.path.exists(os.path.dirname(args.output)):
|
|
os.makedirs(os.path.dirname(args.output))
|
|
|
|
output_str = generate_general_syscall_doc(args.input, args.level)
|
|
|
|
with open(args.output, "w") as output_file:
|
|
output_file.write(output_str)
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main())
|