aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2021-01-06 21:45:37 +0100
committerDavid Robillard <d@drobilla.net>2021-01-06 21:45:37 +0100
commita6fa6c45a4df2e0a15ce40437fb03063c9c68891 (patch)
tree6fc7a6f2e0eff5585e3e94f1ccde9f52d05c6f6f
parent53722d1e027afde63a78ee89e899f6b578c3a066 (diff)
downloadserd-a6fa6c45a4df2e0a15ce40437fb03063c9c68891.tar.gz
serd-a6fa6c45a4df2e0a15ce40437fb03063c9c68891.tar.bz2
serd-a6fa6c45a4df2e0a15ce40437fb03063c9c68891.zip
dox_to_sphinx.py: Emit documentation in groups
-rwxr-xr-xscripts/dox_to_sphinx.py75
1 files changed, 23 insertions, 52 deletions
diff --git a/scripts/dox_to_sphinx.py b/scripts/dox_to_sphinx.py
index f6271ae8..b88a484f 100755
--- a/scripts/dox_to_sphinx.py
+++ b/scripts/dox_to_sphinx.py
@@ -548,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():
@@ -582,17 +561,17 @@ 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)
if len(record["briefdescription"]) > 0:
@@ -600,24 +579,20 @@ def emit_groups(index, output_dir, symbol_dir_name, force):
if len(record["detaileddescription"]) > 0:
rst.write(record["detaileddescription"] + "\n\n")
- # Emit TOC
- rst.write(".. toctree::\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))
-
- rst.write("\n")
+ for name, symbol in child_symbols.items():
+ rst.write("\n")
+ rst.write(document_markup(index, lang, symbol))
+ 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
@@ -639,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__":
@@ -668,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")