Meade Command Wiki Parser (#116)

* Updated meade header parser for wiki
* Added Example as new sub header, swapped place on command and info

Author: christian-kardach

.gitignore

@@ -7,3 +7,4 @@ CMakeLists.txt
 CMakeListsPrivate.txt
 
 Configuration_local*
+MeadeToWikiOutput.txt

scripts/MeadeCommandParser.py

@@ -1,13 +1,22 @@
-# Helper script for parsingt the header file of MEADE
-# Can be used to populate WIKI
+"""
+Helper script for parsingt the header file of MEADE
+
+USAGE:
+ - Ensure you have a Python interperter working for VSCode
+ - Execute this file by pressing the little green "Play" button in the top-right corner
+ - Output will be written to "./scripts/MeadeToWikiOutput.txt" directory
+ - Copy entire content of the file and paste it on the wiki page
+"""
 
 import os
+import re
 
 MEADE_HPP = "..\\src\\MeadeCommandProcessor.cpp"
 MODULE_PATH = os.path.dirname(os.path.realpath(__file__))
 START_LINE = 0
 END_LINE = 0
 
+
 class Family:
     def __init__(self):
         self.name = None
@@ -16,15 +25,104 @@ def __init__(self):
 
 class Command:
     def __init__(self):
-        self.command = None
-        self.short = str()
-        self.long = str()
-        self.returns = str()
+        self.__command = None
+        self.__description = str()
+        self.__information = list()
+        self.__returns = list()
+        self.__parameters = list()
+        self.__remarks = list()
+        self.__example = list()
+
+    def set_data(self, attribute, data):
+        setattr(self, attribute, data)
+    
+    @property
+    def command(self):
+        return self.__command
+
+    @command.setter
+    def command(self, val):
+        self.__command = val
+    
+    @property
+    def description(self):
+        return self.__description
+
+    @description.setter
+    def description(self, val):
+        self.__description = val
+
+    @property
+    def information(self):
+        return self.__information
+
+    @information.setter
+    def information(self, val):
+        if val not in self.__information:
+            self.__information.append(val)
+
+    @property
+    def returns(self):
+        return self.__returns
+
+    @returns.setter
+    def returns(self, val):
+        if val not in self.__returns:
+            self.__returns.append(val)
+
+    @property
+    def parameters(self):
+        return self.__parameters
+
+    @parameters.setter
+    def parameters(self, val):
+        if val not in self.__parameters:
+            self.__parameters.append(val)
+    
+    @property
+    def remarks(self):
+        return self.__remarks
+
+    @remarks.setter
+    def remarks(self, val):
+        if val not in self.__remarks:
+            self.__remarks.append(val)
+    
+    @property
+    def example(self):
+        return self.__example
+
+    @example.setter
+    def example(self, val):
+        if val not in self.__example:
+            self.__example.append(val)
+
+
+command_sepparators = ["Description::",
+                       "Information:",
+                       "Returns:",
+                       "Parameters:",
+                       "Remarks:",
+                       "Remarks:",
+                       "Example:",
+                       "//"]
+
+
+def remove_line_prefix(line):
+    striped_line = line.replace("//", "").lstrip()
+    striped_line = striped_line.replace("\"", "`")
+    return striped_line
 
-def removeLinePrefix(line):
-    return line.replace("// ", "").strip()
+def check_command_sepparator(line):
+    striped_line = line.replace("//", "").lstrip()
+    if line in command_sepparators:
+        return True
+    elif line.startswith("//") and striped_line in command_sepparators: 
+        return True
+    else:
+        return False
 
-#Meade hpp File
+# Meade hpp File
 with open(os.path.join(MODULE_PATH, MEADE_HPP)) as f:
     content = f.readlines()
 content = [x.strip() for x in content]
@@ -40,75 +138,165 @@ def removeLinePrefix(line):
     raise Exception("Could not locate start and stop of comment block.")
 
 START_LINE = startStop[0]
-END_LINE  = startStop[1]
+END_LINE = startStop[1]
 
 print(("Start and end of block: {0}, {1} ".format(START_LINE, END_LINE)))
 
-familyDividers = []
+family_dividers = []
 for i in range(START_LINE, END_LINE):
     for div in ["//------------------------------------------------------------------", "// --"]:
         if div in content[i]:
-            familyDividers.append(i)
+            family_dividers.append(i)
 
-print(("Found {0} family groups ".format(len(familyDividers))))
+print(("Found {0} family groups ".format(len(family_dividers))))
 
-allCommands = []
-for i in range(len(familyDividers) - 1):
-    start = familyDividers[i]
-    end = familyDividers[i + 1]
+all_commands = []
+for i in range(len(family_dividers) - 1):
+#for i in range(0, 6):
+    start = family_dividers[i] + 1
+    end = family_dividers[i + 1]
+
+    new_family = Family()
+    new_family.name = remove_line_prefix(content[start])
+
+    # Find command groups
+    sub_offsets = list()
+    sub_offsets.append(start+2)
+    for j in range(start+2, end):
+        if content[j] == "//":
+            sub_offsets.append(j)
 
-    newFamily = Family()
-    if "//------------------------------------------------------------------" in content[start]:
-        newFamily.name = removeLinePrefix(content[start + 1])
-    elif "// --" in content[start]:
-        nameCleanup = content[start].replace("// -- ", "")
-        nameCleanup = nameCleanup.replace(" --", "")
-        newFamily.name = nameCleanup
-
-    for y in range(start + 1, end - 1):
-        newCommand = Command()
-
-        # Command
-        if content[y].startswith("// :"):
-            newCommand.command = removeLinePrefix(content[y])
-        
-            # Short Description
-            newCommand.short = removeLinePrefix(content[y + 1])
-            y+=2
-
-            k = y
-            while not content[k].startswith("//      Returns:"):
-                newCommand.long += removeLinePrefix(content[k])
-                k += 1
-            y = k
+    for k in range(0, len(sub_offsets)-1):
+        command = Command()
+        sub_start = sub_offsets[k]
+        sub_end = sub_offsets[k+1]
 
+        for l in range(sub_start, sub_end):
+            if content[l] == "//":
+                continue
+            
+            # Command
+            if content[l].startswith("// :"):
+                command.command = remove_line_prefix(content[l])
+
+            # Description
+            if content[l].startswith("//") and "Description:" in content[l]:
+                command.description = remove_line_prefix(content[l+1])
+
+            # Information
+            if content[l].startswith("//") and "Information:" in content[l]:
+                m = l+1
+                while not check_command_sepparator(content[m]):
+                    command.information = remove_line_prefix(content[m])
+                    m += 1
+                l = m
+            
+            # Returns
+            if content[l].startswith("//") and "Returns:" in content[l]:
+                m = l+1
+                while not check_command_sepparator(content[m]):
+                    command.returns = remove_line_prefix(content[m])
+                    m += 1
+                l = m
+
+            # Remarks
+            if content[l].startswith("//") and "Remarks:" in content[l]:
+                m = l+1
+                while not check_command_sepparator(content[m]):
+                    command.remarks = remove_line_prefix(content[m])
+                    m += 1
+                l = m
+
+            # Parameters
+            if content[l].startswith("//") and "Parameters:" in content[l]:
+                m = l+1
+                while not check_command_sepparator(content[m]):
+                    command.parameters = remove_line_prefix(content[m])
+                    m += 1
+                l = m
+
+             # Example
+            if content[l].startswith("//") and "Example:" in content[l]:
+                m = l+1
+                while not check_command_sepparator(content[m]):
+                    command.example = remove_line_prefix(content[m])
+                    m += 1
+                l = m
 
-        if content[y].startswith("//      Returns:"):
-            newCommand.returns += content[y].replace("//      Returns: ", "")
-            k = y+1
-            while content[k] != "//":
-                newCommand.returns += content[k].replace("//               ", " ").strip()
-                k += 1
-            y = k
-        
-        if newCommand.command:
-            newFamily.commands.append(newCommand)
+        new_family.commands.append(command)
+    all_commands.append(new_family)
+
+def output_wiki():
+    """
+    Writes content to a MeadeToWikiOutput.txt file 
+    """
 
-    allCommands.append(newFamily)
+    f = open("./scripts/MeadeToWikiOutput.txt", "w")
+    
+    for fam in all_commands:
+        f.write(f"## {fam.name}\n")
+        f.write("<br>\n\n")
+
+        for cmd in fam.commands:
+            f.write(f"### {cmd.description}\n")
+            
+            if cmd.information:
+                #f.write("**Information:**\n")
+                for line in cmd.information:
+                    f.write(f"{line}")
+                f.write("\n\n")
+
+            f.write(f"**Command:**\n")
+            f.write(f"`{cmd.command}`\n")
+            f.write("\n")  
+
+            f.write("**Returns:**\n")
+            for line in cmd.returns:
+                f.write(f"- {line}\n")
+            f.write("\n")
+
+            if cmd.parameters:
+                f.write("**Parameters:**\n")
+                for param in cmd.parameters:
+                    f.write(f"- {param}\n")
+                f.write("\n")
 
+            if cmd.remarks:
+                f.write("**Remarks:**\n")
+                for param in cmd.remarks:
+                    f.write(f"{param}\n")
+                f.write("\n")
 
-# Example of printing output
-for fam in allCommands:
-    print("***** {0} *****".format(fam.name))
-    print("Command Count: {0}".format(len(fam.commands)))
+            if cmd.example:
+                f.write("**Example:**\n")
+                for param in cmd.example:
+                    f.write(f"- {param}\n")
+                f.write("\n")
+            
+            f.write("<br>")
+            f.write("\n")
+            f.write("\n")
+
+    f.write("\n\n")
+
+    f.close()
+    print("File written to: ./scripts/MeadeToWikiOutput.txt")
+
+if __name__ == "__main__":
+    output_wiki()
+
+"""
+# Output Excample
+for fam in all_commands:
+    print("-----")
+    print(fam.name)
     for cmd in fam.commands:
-        print("\tCommand: {0}".format(cmd.command))
-        print("\tShort: {0}".format(cmd.short))
-        print("\tLong Description: {0}".format(cmd.long))
-        print("\tReturns: {0}".format(cmd.returns))
-        print("\r")
-
-print("Family Count: {0}".format(len(allCommands)))
-for fam in allCommands:
-    print("{0}".format(fam.name))
-    print("\t{0}".format(len(fam.commands)))
+        print("############################")
+        print(f"Command: {cmd.command}")
+        print(f"Description: {cmd.description}")
+        print(f"Information: {cmd.information}")
+        print(f"Returns: {cmd.returns}")
+        print(f"Parameters: {cmd.parameters}")
+        print(f"Remarks: {cmd.remarks}")
+        
+"""