aboutsummaryrefslogtreecommitdiffstats
path: root/scripts/dox_to_sphinx.py
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2021-01-06 23:53:32 +0100
committerDavid Robillard <d@drobilla.net>2021-01-06 23:53:32 +0100
commit94e30b9c3c188dfdf4765f026872f95ea3cfdda2 (patch)
tree2a74ee400a172703137e5273df2ac93d588523cc /scripts/dox_to_sphinx.py
parentd2a6fd3f725f7f174535c49d78d07567e12c84d8 (diff)
downloadpugl-94e30b9c3c188dfdf4765f026872f95ea3cfdda2.tar.gz
pugl-94e30b9c3c188dfdf4765f026872f95ea3cfdda2.tar.bz2
pugl-94e30b9c3c188dfdf4765f026872f95ea3cfdda2.zip
Simplify documentation structure and use LV2 theme
Diffstat (limited to 'scripts/dox_to_sphinx.py')
-rwxr-xr-xscripts/dox_to_sphinx.py108
1 files changed, 47 insertions, 61 deletions
diff --git a/scripts/dox_to_sphinx.py b/scripts/dox_to_sphinx.py
index b4eee9f..b88a484 100755
--- a/scripts/dox_to_sphinx.py
+++ b/scripts/dox_to_sphinx.py
@@ -238,7 +238,7 @@ def heading(text, level):
chars = ("#", "*", "=", "-", "^", '"')
line = chars[level] * len(text)
- return "%s\n%s\n%s\n\n" % (line if level < 3 else "", text, line)
+ return "%s%s\n%s\n\n" % (line + "\n" if level < 3 else "", text, line)
def dox_to_rst(index, lang, node):
@@ -257,6 +257,12 @@ def dox_to_rst(index, lang, node):
return " " + markup.strip()
+ if node.tag == "lsquo":
+ return "‘"
+
+ if node.tag == "rsquo":
+ return "’"
+
if node.tag == "computeroutput":
assert len(node) == 0
return "``%s``" % node.text
@@ -332,7 +338,7 @@ def description_markup(index, lang, node):
assert not (node.tag == "briefdescription" and len(node) > 1)
assert len(node.text.strip()) == 0
- return "".join([dox_to_rst(index, lang, child) for child in node])
+ return "".join([dox_to_rst(index, lang, child) for child in node]).strip()
def set_descriptions(index, lang, definition, record):
@@ -454,6 +460,9 @@ def read_definition_doc(index, lang, root):
name,
)
+ elif kind == "variable":
+ record["definition"] = member.find("definition").text
+
def declaration_string(record):
"""
@@ -474,6 +483,11 @@ def declaration_string(record):
result += record["prototype"]
elif kind == "typedef":
result += record["definition"]
+ elif kind == "variable":
+ if "parent" in record:
+ result += "%s %s" % (record["type"], local_name(record["name"]))
+ else:
+ result += record["definition"]
elif "type" in record:
result += "%s %s" % (record["type"], local_name(record["name"]))
else:
@@ -497,9 +511,9 @@ def document_markup(index, lang, record):
markup += ".. %s:: %s\n" % (role, declaration_string(record))
# Write main description blurb
- markup += "\n"
- markup += indent(record["briefdescription"], 1)
- markup += indent(record["detaileddescription"], 1)
+ markup += "\n" + indent(record["briefdescription"] + "\n", 1)
+ if len(record["detaileddescription"]) > 0:
+ markup += "\n" + indent(record["detaileddescription"], 1) + "\n"
assert (
kind in ["class", "enum", "namespace", "struct", "union"]
@@ -510,7 +524,7 @@ def document_markup(index, lang, record):
child_indent = 0 if kind == "namespace" else 1
# Write inline children if applicable
- markup += "\n"
+ markup += "\n" if "children" in record else ""
for child_id in record.get("children", []):
child_record = index[child_id]
child_role = sphinx_role(child_record, lang)
@@ -524,7 +538,6 @@ def document_markup(index, lang, record):
markup += indent(child_header, child_indent)
markup += indent(child_record["briefdescription"], child_indent + 1)
markup += indent(child_record["detaileddescription"], child_indent + 1)
- markup += "\n"
return markup
@@ -535,28 +548,7 @@ def symbol_filename(name):
return name.replace("::", "__")
-def emit_symbols(index, lang, symbol_dir, force):
- """Write a description file for every symbol documented in the index."""
-
- for record in index.values():
- if (
- record["kind"] in ["group", "namespace"]
- or "parent" in record
- and index[record["parent"]]["kind"] != "group"
- ):
- continue
-
- name = record["name"]
- filename = os.path.join(symbol_dir, symbol_filename("%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(local_name(name), 3))
- rst.write(document_markup(index, lang, record))
-
-
-def emit_groups(index, output_dir, symbol_dir_name, force):
+def emit_groups(index, lang, output_dir, force):
"""Write a description file for every group documented in the index."""
for record in index.values():
@@ -569,40 +561,38 @@ def emit_groups(index, output_dir, symbol_dir_name, force):
raise FileExistsError("File already exists: '%s'" % filename)
with open(filename, "w") as rst:
- rst.write(heading(record["title"], 2))
+ rst.write(heading(record["title"], 1))
# Get all child group and symbol names
- group_names = []
- symbol_names = []
+ child_groups = {}
+ child_symbols = {}
for child_id in record["children"]:
child = index[child_id]
if child["kind"] == "group":
- group_names += [child["name"]]
+ child_groups[child["name"]] = child
else:
- symbol_names += [child["name"]]
+ child_symbols[child["name"]] = child
# Emit description (document body)
- rst.write(record["briefdescription"] + "\n\n")
- rst.write(record["detaileddescription"] + "\n\n")
-
- # Emit TOC
- rst.write(".. toctree::\n")
+ if len(record["briefdescription"]) > 0:
+ rst.write(record["briefdescription"] + "\n\n")
+ if len(record["detaileddescription"]) > 0:
+ rst.write(record["detaileddescription"] + "\n\n")
- # Emit groups at the top of the TOC
- for group_name in group_names:
- rst.write("\n" + indent(group_name, 1))
+ if len(child_groups) > 0:
+ # Emit TOC for child groups
+ rst.write(".. toctree::\n\n")
+ for name, group in child_groups.items():
+ rst.write(indent(group["name"], 1) + "\n")
# Emit symbols in sorted order
- for symbol_name in sorted(symbol_names):
- path = "/".join(
- [symbol_dir_name, symbol_filename(symbol_name)]
- )
- rst.write("\n" + indent(path, 1))
+ for name, symbol in child_symbols.items():
+ rst.write("\n")
+ rst.write(document_markup(index, lang, symbol))
+ rst.write("\n")
- rst.write("\n")
-
-def run(index_xml_path, output_dir, symbol_dir_name, language, force):
+def run(index_xml_path, output_dir, language, force):
"""Write a directory of Sphinx files from a Doxygen XML directory."""
# Build skeleton index from index.xml
@@ -624,11 +614,14 @@ def run(index_xml_path, output_dir, symbol_dir_name, language, force):
for root in definition_docs:
read_definition_doc(index, language, root)
+ # Create output directory
+ try:
+ os.makedirs(output_dir)
+ except OSError:
+ pass
+
# Emit output files
- symbol_dir = os.path.join(output_dir, symbol_dir_name)
- os.makedirs(symbol_dir, exist_ok=True)
- emit_symbols(index, language, symbol_dir, force)
- emit_groups(index, output_dir, symbol_dir_name, force)
+ emit_groups(index, language, output_dir, force)
if __name__ == "__main__":
@@ -653,13 +646,6 @@ if __name__ == "__main__":
help="language domain for output",
)
- ap.add_argument(
- "-s",
- "--symbol-dir-name",
- default="symbols",
- help="name for subdirectory of symbol documentation files",
- )
-
ap.add_argument("index_xml_path", help="path index.xml from Doxygen")
ap.add_argument("output_dir", help="output directory")