tools/kemi: add dockstrings to the mocking (#3818)

kemi_mock.py can now optionally consume documentation information
generated by the vscode-kamailio-hover project

misc/tools/kemi/python_mock/README.md

@@ -2,7 +2,7 @@
 
 Generate a mocking framework base on the output of app_python.api_list
 
-Usage:
+### Usage:
 ```
 /usr/sbin/kamctl rpc app_python.api_list > api.json
 ./kemi_mock.py api.json > KSR.py
@@ -15,6 +15,19 @@ the Union type add the --no-union flag
 ./kemi_mock.py api.json --no-union > KSR.py
 ```
 
+### Usage with Documentation:
+run the generate.py from the following project
+
+https://github.com/braams/vscode-kamailio-hover
+
+this creates a modules.json file in a tmp directory. This file can be used to generate the KSR.py file with documentation
+
+pass the modules.json as a 2nd parameter to kemi_mock.py
+```
+./kemi_mock.py api.json modules.json > KSR.py
+```
+
+## Mocking 
 Return values can be injected through the dictionary \_mock\_data
 
 ```python

misc/tools/kemi/python_mock/kemi_mock.py

@@ -113,21 +113,41 @@ def printFunction(module_name, func, indent):
     else:
         print(prefix + "def " + func['name'] +"("+params+"):")
 
+    generate_function_doc(module_name, func, prefix)
+
     print(prefix + "\tprint(\"Calling " + log_format_params + "\" % "+log_params+")")
     printMocReturn(module_name, func, indent+1)
     print("")
 
 
+def generate_function_doc(module_name, func, prefix):
+    if documentation is not None and module_name in documentation:
+        function_parts = func['name'].split("_")
+        for i in range(len(function_parts), 0, -1):
+            function_prefix = "_".join(function_parts[:i])
+            if function_prefix in documentation[module_name]["functions"]:
+                print(prefix + "\t\"\"\"")
+                documentation_lines = documentation[module_name]["functions"][function_prefix].split("\n")
+                for line in documentation_lines:
+                    print(prefix + "\t" + line)
+                print(prefix + "\t\"\"\"")
+                break
+
+
 classes = defaultdict(list)
 
 if len(sys.argv) < 2:
     print("Please specify the json file to parse")
     sys.exit(-1)
 
+documentation = None
 if len(sys.argv) > 2:
     for i in range(2,len(sys.argv)):
         if sys.argv[i] == "--no-union":
             noUnion = True
+        else:
+            with open(sys.argv[i]) as f:
+                documentation = json.load(f)
 
 if not noUnion:
     print("from typing import Union")
@@ -193,12 +213,23 @@ for func in classes['']:
     print("")
     printFunction('', func, 0)
 
+
+def document_module(module_name):
+    if documentation is not None and module_name in documentation:
+        print("\"\"\"")
+        documentation_lines = documentation[module_name]["overview"].split("\n")
+        for line in documentation_lines:
+            print("" + line)
+        print("\"\"\"")
+
+
 for module_name in classes.keys():
     if module_name != "":
         if module_name in reserved_keywords:
             print("setattr(sys.modules[__name__], '" + module_name + "', " + module_name.capitalize() + "())")
         else:
             print(module_name + " = "+module_name.capitalize()+"()")
+        document_module(module_name)
 
 print("")