From da1e73fe96d2f72836d92b4d2fa0171db3e70e76 Mon Sep 17 00:00:00 2001
From: Anna Lyons <Anna.Lyons@data61.csiro.au>
Date: Wed, 9 May 2018 16:44:04 +1000
Subject: [PATCH] manual: use int level in parse_doxygen_xml.py

The level argument to parse_doxygen_xml.py was previously a latex section header (either subsection
or subsubsection). This change converts the argument to numerical which is more robust and is not
limited to 2 specific levels.

This change
- alters the level argument to be an int, where 0 = highest level header,
- removes the translation of latex header to markdown,
- adds a new 'level_to_header' function to the generator class, which translates the level number
  to a header for that specific output type.
---
 manual/Makefile                   |  6 +++---
 manual/tools/parse_doxygen_xml.py | 30 +++++++++++++++++++-----------
 2 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/manual/Makefile b/manual/Makefile
index 630522dde..ba6e8714b 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -122,12 +122,12 @@ ${DoxygenXml}/%.xml: doxygen
 # General object invocations are listed as subsections
 ${GeneratedLatexDir}/ObjectApi.tex: ${DoxygenXml}/group__ObjectApi.xml
 	@echo "====> Generating $@"
-	${Q}${PYTHON} ${GenerationTool} --level subsection --input $< --output $@
+	${Q}${PYTHON} ${GenerationTool} --level 2 --input $< --output $@
 
 # Everything else is listed as subsubsections
 ${GeneratedLatexDir}/%.tex: ${DoxygenXml}/group__%.xml
 	@echo "====> Generating $@"
-	${Q}${PYTHON} ${GenerationTool} --level subsubsection --input $< --output $@
+	${Q}${PYTHON} ${GenerationTool} --level 3 --input $< --output $@
 
 # Collect generated latex files into single rule
 generated-latex: ${GeneratedLatexDir}/GeneralSystemCalls.tex \
@@ -146,7 +146,7 @@ generated-latex: ${GeneratedLatexDir}/GeneralSystemCalls.tex \
 # Markdown files translated from doxygen-generated xml
 ${GeneratedMarkdownDir}/%.md: ${DoxygenXml}/group__%.xml Makefile
 	@echo "====> Generating $@"
-	${Q}${PYTHON} ${GenerationTool} --format markdown --level subsubsection --input $< --output $@
+	${Q}${PYTHON} ${GenerationTool} --format markdown --level 2 --input $< --output $@
 
 # Collect generated markdown files into single rule
 generated-markdown: ${GeneratedMarkdownDir}/GeneralSystemCalls.md \
diff --git a/manual/tools/parse_doxygen_xml.py b/manual/tools/parse_doxygen_xml.py
index 15ef8b153..6050f2abf 100755
--- a/manual/tools/parse_doxygen_xml.py
+++ b/manual/tools/parse_doxygen_xml.py
@@ -323,7 +323,7 @@ class LatexGenerator(Generator):
 {%(ret)s}
 {%(details)s}
         """ % {
-            "level": level,
+            "level": self.level_to_header(level),
             "label": manual_node["label"],
             "name": self.text_escape(manual_node["name"]),
             "brief": self.todo_if_empty(self.parse_brief(member)),
@@ -333,6 +333,18 @@ class LatexGenerator(Generator):
             "details": details,
         }
 
+    def level_to_header(self, level):
+        if level == 0:
+            return 'chapter'
+        elif level == 1:
+            return 'section'
+        elif level == 2:
+            return 'subsection'
+        elif level == 3:
+            return 'subsubsection'
+        else:
+            return 'paragraph'
+
 class MarkdownGenerator(Generator):
     """
     A class that represents the generator for Doxygen to Markdown. A child of the Generator class
@@ -436,13 +448,6 @@ Type | Name | Description
                     "desc": self.todo_if_empty(param_info.get("desc", "").strip()),
         }
 
-    def level_to_markdown(self, string):
-        """Converts the level to a corresponding markdown heading prefix"""
-
-        if string == "subsubsection":
-            return "####"
-        return "###"
-
     def generate_api_doc(self, level, member, params, ret, details):
         manual_node = member.manual
 
@@ -471,7 +476,7 @@ Type | Name | Description
 
 %(details)s
         """ % {
-                "hash": self.level_to_markdown(level),
+                "hash": self.level_to_header(level),
                 "name": self.text_escape(manual_node["name"]),
                 "label": manual_node["label"],
                 "brief": self.todo_if_empty(self.parse_brief(member)),
@@ -481,6 +486,9 @@ Type | Name | Description
                 "details": details_string,
         }
 
+    def level_to_header(self, level):
+        return (level + 1) * '#'
+
 def generate_general_syscall_doc(generator, input_file_name, level):
     """
     Takes a path to a file containing doxygen-generated xml,
@@ -521,8 +529,8 @@ def process_args():
     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")
+    parser.add_argument("-l", "--level", type=int,
+                        help="Level for each method, 0 = top level")
 
     return parser