update: 把接口文档的几个函数单独拎出来

tools/capi_get.py

@@ -0,0 +1,164 @@
+import re
+import io
+import os
+
+def get_file_list(paths):
+    file_list = []
+    for path in paths:
+        for home, _, files in os.walk(path):
+            for filename in files:
+                if filename.endswith(".c"):
+                    file_list.append(os.path.join(home, filename))
+    return file_list
+
+#注释的格式：
+# /*
+# @module  模块的调用名
+# @summary 模块的简短描述信息
+# @version 版本号，可选
+# @data    日期，可选
+# */
+# /*
+# @api/function module.function(调用时用到的完整函数名)
+# @string 第一个参数，@后跟参数类型，空格后跟参数解释
+# @number[opt=nil] 第二个参数，默认值为nil
+# @table[opt={}] 第三个参数，默认值为{}
+# ...根据实际，列出所有参数
+# @return 类型 返回的第一个值，这里是解释
+# @return string 返回的第二个值，类型为string
+# ...根据实际，列处所有返回值
+# @usage
+# --使用的例子，可多行
+# lcoal a,b,c = module.function("test",nil,{1,2,3})
+# */
+# static int l_module_function(lua_State *L) {
+#     //一堆代码
+# }
+########################################################
+#数据结构：
+# modules = [
+#     {
+#         'module': 'adc',
+#         'summary': '数模转换',
+#         'url': 'https://xxxxxx',
+#         'api':[
+#             {
+#                 'api':'adc.read(id)',
+#                 'summary': '读取adc通道',
+#                 'args': [
+#                     {
+#                         'type': 'int',
+#                         'summary': '通道id,与具体设备有关,通常从0开始'
+#                     }
+#                 ],
+#                 'return': [
+#                     {
+#                         'type': 'int',
+#                         'summary': '原始值'
+#                     },
+#                     {
+#                         'type': 'int',
+#                         'summary': '计算后的值'
+#                     }
+#                 ],
+#                 'usage': '-- 打开adc通道2,并读取\nif adc.open(2) then...'
+#             },
+#         ]
+#     }
+# ]
+def get_modules(file_list):
+    modules = []
+    for file in file_list:
+        text = ""
+        try:
+            f = io.open(file,"r",encoding="utf-8")
+            text = f.read()
+            f.close()
+        except:
+            #print("read fail, maybe not use utf8")
+            continue
+
+        module = {}
+
+        file = file.replace("\\","/")
+        if file.rfind("luat/") >= 0:
+            file = file[file.rfind("luat/"):]
+            module["url"] = "https://gitee.com/openLuat/LuatOS/tree/master/"+file
+        else:
+            module["url"] = ""
+
+
+        # 注释头
+        r = re.search(r"/\* *\n *@module *(\w+)\n *@summary *(.+)\n",text,re.I|re.M)
+        if r:
+            module["module"] = r.group(1)
+            module["summary"] = r.group(2)
+            module["api"] = []
+        else:
+            continue
+
+        for mstep in range(len(modules)-1,-1,-1):
+            if modules[mstep]["module"] == module["module"]:
+                module["api"] = modules[mstep]["api"]
+                del modules[mstep]
+                module["url"] = ""
+
+        #后面的数据
+        lines = text.splitlines()
+        line_now = 0
+        while line_now<len(lines)-3:
+            #匹配api完整名称行
+            name = re.search(r" *@api *(.+) *",lines[line_now+2],re.I)
+            if not name:
+                name = re.search(r" *@function *(.+) *",lines[line_now+2],re.I)
+            if lines[line_now].startswith("/*") and name:
+                api = {}
+                api["api"] = name.group(1)
+                api["summary"] = re.search(r" *(.+) *",lines[line_now+1],re.I).group(1)
+                line_now += 3
+                api["args"] = []
+                api["return"] = []
+                api["usage"] = ""
+                arg_re = r" *@([^ ]+) +(.+) *"
+                return_re = r" *@return *([^ ]+) +(.+) *"
+                #匹配输入参数
+                while True:
+                    arg = re.search(arg_re,lines[line_now],re.I)
+                    arg_return = re.search(return_re,lines[line_now],re.I)
+                    if arg and not arg_return:
+                        api["args"].append({'type':arg.group(1),'summary':arg.group(2)})
+                        line_now+=1
+                    else:
+                        break
+                #匹配返回值
+                while True:
+                    arg = re.search(return_re,lines[line_now],re.I)
+                    if arg:
+                        api["return"].append({'type':arg.group(1),'summary':arg.group(2)})
+                        line_now+=1
+                    else:
+                        break
+                #匹配用法例子
+                while True:
+                    arg = re.search(" *@usage *",lines[line_now],re.I)
+                    if arg:
+                        line_now+=1
+                        while lines[line_now].find("*/") < 0:
+                            api["usage"] += lines[line_now]+"\n"
+                            line_now+=1
+                    else:
+                        line_now+=2
+                        break
+                module["api"].append(api)
+            else:
+                line_now += 1
+        #没有api的包，不导入
+        if len(module["api"]) > 0:
+            modules.append(module)
+            print(module["module"])
+
+    #按名字排个序
+    def sorfFnc(k):
+        return k["module"]
+    modules.sort(key=sorfFnc)
+    return modules

tools/make_doc_file.py

@@ -0,0 +1,52 @@
+import shutil
+import os
+
+def make(path,modules,index_text):
+    try:
+        shutil.rmtree(path)
+        os.mkdir(path)
+    except:
+        pass
+
+    doc = open(path+"index.rst", "a+",encoding='utf-8')
+    doc.write(index_text)
+    
+    for module in modules:
+        mdoc = open("../../luatos-wiki/api/"+module["module"]+".md", "a+",encoding='utf-8')
+        mdoc.write("# "+module["module"]+" - "+module["summary"]+"\n\n")
+        if len(module["url"]) > 0:
+            mdoc.write("> 本页文档由[这个文件]("+module["url"]+")自动生成。如有错误，请提交issue或帮忙修改后pr，谢谢！\n\n")
+        doc.write("   "+module["module"]+"\n")
+        for api in module["api"]:
+            mdoc.write("## "+api["api"]+"\n\n")
+            mdoc.write(api["summary"]+"\n\n")
+
+            mdoc.write("**参数**\n\n")
+            if len(api["args"]) > 0:
+                mdoc.write("|传入值类型|解释|\n|-|-|\n")
+                for arg in api["args"]:
+                    mdoc.write("|"+arg["type"].replace("|","\|")+"|"+arg["summary"].replace("|","\|")+"|\n")
+                mdoc.write("\n")
+            else:
+                mdoc.write("无\n\n")
+
+            mdoc.write("**返回值**\n\n")
+            if len(api["return"]) > 0:
+                mdoc.write("|返回值类型|解释|\n|-|-|\n")
+                for arg in api["return"]:
+                    mdoc.write("|"+arg["type"].replace("|","\|")+"|"+arg["summary"].replace("|","\|")+"|\n")
+                mdoc.write("\n")
+            else:
+                mdoc.write("无\n\n")
+
+            mdoc.write("**例子**\n\n")
+            if len(api["usage"]) == 0:
+                mdoc.write("无\n\n")
+            else:
+                mdoc.write("```lua\n"+api["usage"]+"\n```\n\n")
+
+            mdoc.write("---\n\n")
+
+        mdoc.close()
+
+    doc.close()