:sparkles: Add working bluetooth receiver

1 files changed, 242 insertions, 0 deletions

diff --git a/utils/python/doc_gen/md_converter.py b/utils/python/doc_gen/md_converter.py
new file mode 100644
index 0000000..ff3a1eb
--- /dev/null
+++ b/utils/python/doc_gen/md_converter.py
@@ -0,0 +1,242 @@
+import re, json, copy
+
+class MarkdownConverter:
+
+    #constructor
+    def __init__(self, type_colour, function_name_colour, separate_defaults = True, display_defaults = False):
+        self.type_colour = type_colour
+        self.function_name_colour = function_name_colour
+        self.separate_defaults = separate_defaults
+        self.display_defaults = display_defaults
+
+    ###
+    # wraps text in a div element with a given color
+    #
+    # @param text the text to wrap
+    # @param color the desired text color
+    #
+    # @return a string representing the now wrapped text
+    ###
+    def wrap_text(self, text, color):
+        return "<div style='color:" + color + "; display:inline-block'>" + text + "</div>"
+
+    ###
+    # removes previously generated markdown from the file.
+    #
+    # @param file_lines a list of lines representing a file.
+    # @param regexp the regular expression that dictates a match.
+    ###
+    def clean(self, file_lines, regexp):
+        start = 0
+        end = 0
+
+        for line_number, line in enumerate(file_lines, 1):
+            result = re.findall(regexp,line)
+
+            if len(result) is not 0:
+                meta_data = json.loads(result[0])
+
+                keys = meta_data.keys()
+
+                #classname indicates the beginning of a meta_data section
+                if 'className' in keys:
+                    start = line_number
+
+                #end indicated the end of a meta_data section
+                if 'end' in keys:
+                    end = line_number - 1
+
+        return file_lines[:start] + file_lines[end:]
+
+    ###
+    # given a member function, this function derives the alternative versions
+    #
+    # @param member_func the member function that is required to be derrived
+    #
+    # @return a list of function dictionaries that contain the alternatives, based on the original
+    ###
+    def derive_functions(self, member_func):
+        member_functions_derived = []
+
+        if len(member_func['params']) is not 0:
+
+            param_index = 0
+
+            for param in member_func['params']:
+                if len(param['default']['name']) is 0:
+                    param_index = param_index + 1
+                else:
+                    break
+
+            bare_function = {
+                'short_name' : member_func['short_name'],
+                'name' : member_func['name'],
+                'params' : [],
+                'description' : member_func['description'],
+                'returns' : member_func['returns'],
+                'notes' : member_func['notes'],
+                'examples' : member_func['examples'],
+                'return_type' : member_func['return_type'],
+            }
+
+            for i in range(0, param_index):
+                bare_function['params'] = bare_function['params'] + [member_func['params'][i]]
+
+            member_functions_derived = member_functions_derived + [bare_function]
+
+            current = copy.copy(bare_function)
+
+            #lists retain references, so we have to copy objects to maintain separation
+            for remainder in range(param_index, len(member_func['params'])):
+                current['params'] = current['params'] + [member_func['params'][remainder]]
+                member_functions_derived = member_functions_derived + [current]
+                current = copy.copy(current)
+
+        else:
+            member_functions_derived = member_functions_derived + [member_func]
+
+        return member_functions_derived
+
+    ###
+    # given a parameter, this function generates text
+    #
+    # @param param the parameter that needs a textual translation
+    #
+    # @return a string representing the parameter
+    ###
+    def gen_param_text(self, param):
+        text = "\n> "
+
+        if param['type'] is not None:
+            text = text + " " + self.wrap_text(param['type'], self.type_colour)
+
+        text = text + " " + param['name']
+
+        if self.display_defaults:
+            if len(param['default']['name']) is not 0:
+                text = text + " `= " + param['default']['name']
+
+                if len(param['default']['value']) is not 0:
+                    text = text + param['default']['value']
+
+                text = text + "`"
+
+        if 'description' in param.keys():
+            text = text +" - " + param['description']
+
+        text = text.encode('ascii','ignore')
+
+        return text
+
+    ###
+    # given a list of member functions, this function returns a list of new lines for the
+    # file currently being processed.
+    #
+    # @param class_name the name of the current class (found in the meta data)
+    # @param member_functions the list of member_functions extracted from XML
+    #
+    # @return a list containing the new lines to be inserted into the current file.
+    ###
+    def gen_member_func_doc(self, class_name, member_functions):
+
+        # this is what a member function dictionary contains.
+        # function = {
+        #     'short_name':"",
+        #     'name':"",
+        #     'return_type':"",
+        #     'params':[],
+        #     'description':[],
+        #     'returns':"",
+        #     'notes':"",
+        #     'examples':"",
+        #     'default':None
+        # }
+
+        lines = []
+
+        for index, member_func in enumerate(member_functions,0):
+
+            member_functions_derived = []
+
+            if index is 0 or member_func['short_name'] != member_functions[index - 1]['short_name']:
+                if class_name == member_func["short_name"]:
+                    lines.append("##Constructor\n")
+                else:
+                    lines.append("##" + member_func["short_name"]+"\n")
+
+            #we want to clearly separate our different level of functions in the DAL
+            #so we present methods with defaults as overloads.
+            if self.separate_defaults is True:
+                member_functions_derived = member_functions_derived + self.derive_functions(member_func)
+
+            for derived_func in member_functions_derived:
+                #---- short name for urls ----
+                lines.append("<br/>\n")
+
+                short_name = ""
+
+                if len(derived_func["return_type"]) is not 0:
+                    short_name = "####" + self.wrap_text(derived_func["return_type"],self.type_colour) + " " +self.wrap_text(derived_func["short_name"], self.function_name_colour)  + "("
+                else:
+                    short_name = "####" + derived_func["short_name"] + "("
+
+                last_param = None
+
+                if len(derived_func['params']) is not 0:
+                    last_param = derived_func['params'][-1]
+
+                #generate parameters for the name of this function
+                for param in derived_func['params']:
+                    text = ""
+
+                    if param['type'] is not None:
+                        text = text + " " + self.wrap_text(param['type'], self.type_colour)
+
+                    text = text + " " + param['name']
+
+                    if param is not last_param:
+                        short_name = short_name + text +", "
+                    else:
+                        short_name = short_name + text
+
+                lines.append(short_name + ")\n")
+                #-----------------------------
+
+                #---- description ----
+                if len(derived_func['description']) is not 0:
+                    lines.append("#####Description\n")
+                    lines.append(' '.join(derived_func['description']) + "\n")
+                #-----------------------------
+
+                #---- parameters ----
+                if len(derived_func['params']) is not 0:
+                    lines.append("#####Parameters\n")
+
+                    for param in derived_func['params']:
+                        lines.append(self.gen_param_text(param) + "\n")
+                #-----------------------------
+
+                #---- returns ----
+                if len(derived_func['returns']) is not 0:
+                    lines.append("#####Returns\n")
+                    lines.append(derived_func['returns'] + "\n")
+                #-----------------------------
+
+                #---- examples ----
+                if len(derived_func['examples']) is not 0:
+                    lines.append("#####Example\n")
+                    lines.append("```cpp\n")
+                    lines.append(derived_func['examples'])
+                    lines.append("```\n")
+                #-----------------------------
+
+                #---- notes ----
+                if len(derived_func['notes']) is not 0:
+                    lines.append("\n!!! note\n")
+                    lines.append("    " + derived_func['notes'].replace('\n','\n    '))
+                    lines.append('\n\n')
+                #-----------------------------
+
+        lines.append("____\n")
+
+        return lines