diff options
| -rwxr-xr-x | scripts/dox_to_sphinx.py | 150 |
1 files changed, 123 insertions, 27 deletions
diff --git a/scripts/dox_to_sphinx.py b/scripts/dox_to_sphinx.py index e94a79a2..347c46d3 100755 --- a/scripts/dox_to_sphinx.py +++ b/scripts/dox_to_sphinx.py @@ -51,7 +51,7 @@ def load_index(index_path): compound_id = compound.get("refid") compound_kind = compound.get("kind") compound_name = compound.find("name").text - if compound_kind in ["dir", "file", "page"]: + if compound_kind in ["dir", "file", "friend", "page"]: continue # Add record for compound (compounds appear only once in the index) @@ -68,8 +68,11 @@ def load_index(index_path): ) for child in compound.findall("member"): + if child.get("kind") in ["friend"]: + continue + if child.get("refid") in index: - assert compound_kind == "group" + assert compound_kind in ["group", "namespace"] continue # Everything has a kind and a name @@ -110,10 +113,14 @@ def resolve_index(index, root): assert "parent" not in child or child["parent"] == parent_id child["parent"] = parent_id - else: - if parent["kind"] in ["class", "struct", "union"]: - assert "parent" not in child or child["parent"] == parent_id - child["parent"] = parent_id + elif child["kind"] == "namespace": + assert child["kind"] == "namespace" + child["parent"] = parent_id + parent["children"] += [child_id] + + elif parent["kind"] in ["class", "struct", "union"]: + assert "parent" not in child or child["parent"] == parent_id + child["parent"] = parent_id if child_id not in parent["children"]: parent["children"] += [child_id] @@ -121,6 +128,8 @@ def resolve_index(index, root): compound = root.find("compounddef") compound_kind = compound.get("kind") + namespaces = {} + if compound_kind == "group": for subgroup in compound.findall("innergroup"): add_child(index, compound.get("id"), subgroup.get("refid")) @@ -128,6 +137,10 @@ def resolve_index(index, root): for klass in compound.findall("innerclass"): add_child(index, compound.get("id"), klass.get("refid")) + elif compound_kind == "namespace": + for child in compound.findall("innernamespace"): + add_child(index, compound.get("id"), child.get("refid")) + for section in compound.findall("sectiondef"): if section.get("kind").startswith("private"): for member in section.findall("memberdef"): @@ -135,6 +148,9 @@ def resolve_index(index, root): del index[member.get("id")] else: for member in section.findall("memberdef"): + if member.get("kind") in ["friend"]: + continue + member_id = member.get("id") add_child(index, compound.get("id"), member_id) @@ -256,7 +272,7 @@ def dox_to_rst(index, lang, node): def field_value(markup): """Return a value for a field as a single line or indented block.""" if "\n" in markup.strip(): - return "\n" + indent(markup, 1) + return "\n\n" + indent(markup.strip(), 1) return " " + markup.strip() @@ -299,7 +315,7 @@ def dox_to_rst(index, lang, node): assert len(description) == 1 markup += "\n\n:param %s: %s" % ( name.text, - field_value(dox_to_rst(index, lang, description[0])), + field_value(dox_to_rst(index, lang, description[0])).strip(), ) return markup + "\n" @@ -345,7 +361,7 @@ def dox_to_rst(index, lang, node): def description_markup(index, lang, node): """Return the markup for a brief or detailed description.""" - assert node.tag == "briefdescription" or node.tag == "detaileddescription" + assert node.tag in ["briefdescription", "detaileddescription"] assert not (node.tag == "briefdescription" and len(node) > 1) assert len(node.text.strip()) == 0 @@ -389,6 +405,9 @@ def plain_text(node): because it parses things itself to generate links. """ + if node is None: + return "" + if node.tag == "sp": markup = " " elif node.text is not None: @@ -421,35 +440,72 @@ def read_definition_doc(index, lang, root): if compound.find("title") is not None: compound_record["title"] = compound.find("title").text.strip() + if compound.get("kind") in ["class", "struct"]: + name = compound_record["name"] + prefix = "" + if "::" in name: + sep = name.find("::") + prefix = name[0 : sep + 2] + + compound_record["supers"] = [] + for base in compound.findall("basecompoundref"): + prot = base.get("prot") + compound_record["supers"] += [ + "{} {}".format(prot, base.text.replace(prefix, "")) + ] + + # Read list of all members + # scopes = {} + # print("LIST OF ALL MEMBERS:") + # if compound.find("listofallmembers") is not None: + # for member in compound.find("listofallmembers"): + # scopes[member.get("refid")] = member.find("scope").text + + # print("COMPOUND NAME: %s" % compound_record["name"]) + # if len(scopes): + # print("SCOPES: %s" % scopes) + # Set documentation for all children for section in compound.findall("sectiondef"): if section.get("kind").startswith("private"): continue + # templateparamlist = compound.find("templateparamlist") + # if templateparamlist is not None: + # for tparam in templateparamlist.findall("param"): + # if tparam.find("declname") is not None: + # print("TEMPLATE PARAM: %s : %s" % (tparam.find("type").text, tparam.find("declname").text)) + for member in section.findall("memberdef"): + if member.get("id") not in index: + continue + kind = member.get("kind") record = index[member.get("id")] set_descriptions(index, lang, member, record) set_template_params(member, record) if compound.get("kind") in ["class", "struct", "union"]: - assert kind in ["function", "typedef", "variable"] + # assert kind in ["function", "typedef", "variable"] record["type"] = plain_text(member.find("type")) if kind == "define": - if member.find('param') is not None: + if member.find("param") is not None: param_names = [] - for param in member.findall('param'): - defname = param.find('defname') - param_names += [defname.text] if defname is not None else [] + for param in member.findall("param"): + defname = param.find("defname") + param_names += ( + [defname.text] if defname is not None else [] + ) - record["prototype"] = "%s(%s)" % (record["name"], ', '.join(param_names)) + record["prototype"] = "%s(%s)" % ( + record["name"], + ", ".join(param_names), + ) elif kind == "enum": for value in member.findall("enumvalue"): - set_descriptions( - index, lang, value, index[value.get("id")] - ) + set_descriptions(index, lang, value, index[value.get("id")]) elif kind == "function": record["prototype"] = "%s %s%s" % ( @@ -481,7 +537,11 @@ def read_definition_doc(index, lang, root): ) elif kind == "variable": - record["definition"] = member.find("definition").text + # record["definition"] = member.find("definition").text + record["definition"] = "%s %s" % ( + plain_text(member.find("type")), + plain_text(member.find("name")), + ) def declaration_string(record): @@ -499,7 +559,11 @@ def declaration_string(record): if "template_params" in record: result = "template <%s> " % record["template_params"] - if kind == "define" and "prototype" in record: + if kind in ["class", "struct"]: + result += local_name(record["name"]) + if len(record["supers"]): + result += " : " + ",".join(record["supers"]) + elif kind == "define" and "prototype" in record: result += record["prototype"] elif kind == "function": result += record["prototype"] @@ -526,6 +590,12 @@ def document_markup(index, lang, record): name = record["name"] markup = "" + if ( + len(record["briefdescription"].strip()) == 0 + and len(record["detaileddescription"].strip()) == 0 + ): + return markup + if name != local_name(name): markup += ".. cpp:namespace:: %s\n\n" % name[0 : name.rindex("::")] @@ -546,20 +616,35 @@ def document_markup(index, lang, record): child_indent = 0 if kind == "namespace" else 1 # Write inline children if applicable - markup += "\n" if "children" in record else "" + markup += "\n" for child_id in record.get("children", []): child_record = index[child_id] child_role = sphinx_role(child_record, lang) + if ( + len(child_record["briefdescription"]) == 0 + and len(child_record["detaileddescription"]) == 0 + ): + continue + child_header = ".. %s:: %s\n\n" % ( child_role, declaration_string(child_record), ) - markup += "\n" markup += indent(child_header, child_indent) - markup += indent(child_record["briefdescription"], child_indent + 1) - markup += indent(child_record["detaileddescription"], child_indent + 1) + + if len(child_record["briefdescription"]) > 0: + markup += ( + indent(child_record["briefdescription"], child_indent + 1) + + "\n\n" + ) + + if len(child_record["detaileddescription"]) > 0: + markup += ( + indent(child_record["detaileddescription"], child_indent + 1) + + "\n\n" + ) return markup @@ -574,23 +659,34 @@ def emit_groups(index, lang, output_dir, force): """Write a description file for every group documented in the index.""" for record in index.values(): - if record["kind"] != "group": + if record["kind"] not in ["group", "namespace"]: continue name = record["name"] + if "::" in name: + continue + filename = os.path.join(output_dir, "%s.rst" % name) if not force and os.path.exists(filename): raise FileExistsError("File already exists: '%s'" % filename) with open(filename, "w") as rst: - rst.write(heading(record["title"], 1)) + if "title" not in record: + print("warning: No title for %s" % filename) + rst.write(heading(name, 1)) + else: + rst.write(heading(record["title"], 1)) + + if record["kind"] == "namespace": + name = record["name"] + rst.write(".. cpp:namespace:: %s\n\n" % name) # Get all child group and symbol names child_groups = {} child_symbols = {} for child_id in record["children"]: child = index[child_id] - if child["kind"] == "group": + if child["kind"] in ["group", "namespace"]: child_groups[child["name"]] = child else: child_symbols[child["name"]] = child |