tools/make_doc_file.py

   1 import shutil
   2 import os
   3 import requests
   4
   5 #bsp.h文件列表
   6 bsp_header_list = [
   7 {"name":"Air780E/Air700E","url":"https://github.com/openLuat/luatos-soc-2022/raw/master/project/luatos/inc/luat_conf_bsp.h"},
   8 {"name":"Air780EP","url":"https://github.com/openLuat/luatos-soc-2023/raw/master/project/luatos/inc/luat_conf_bsp.h"},
   9 {"name":"Air601","url":"https://github.com/openLuat/luatos-soc-air101/raw/master/app/port/luat_conf_bsp.h"},
  10 {"name":"Air101/Air103","url":"https://github.com/openLuat/luatos-soc-air101/raw/master/app/port/luat_conf_bsp.h"},
  11 {"name":"Air105","url":"https://github.com/openLuat/luatos-soc-air105/raw/master/application/include/luat_conf_bsp.h"},
  12 {"name":"ESP32C3","url":"https://github.com/openLuat/luatos-soc-idf5/raw/master/luatos/include/luat_conf_bsp.h"},
  13 {"name":"ESP32S3","url":"https://github.com/openLuat/luatos-soc-idf5/raw/master/luatos/include/luat_conf_bsp.h"},
  14 ]
  15 print("getting bsp.h files...")
  16 for bsp in bsp_header_list:
  17     # print("getting "+bsp["name"]+"...")
  18     res = ""
  19     #有时候获取不到完整的数据，报错的页面就是html
  20     while len(res) < 200 or res.find("</title>") != -1:
  21         res = requests.get(bsp["url"]).text
  22         # print(res)
  23     bsp["url"] = res
  24     # print("done "+ str(len(bsp["url"])) + " bytes")
  25
  26 def is_supported(tag, bsp) :
  27     if bsp["url"].find(" "+tag+" ") >= 0 or bsp["url"].find(" "+tag+"\r") >= 0 or bsp["url"].find(" "+tag+"\n") >= 0:
  28         return True
  29
  30 def get_tags(tag, is_api = False):
  31     if len(tag) == 0:
  32         if is_api:
  33             return ""
  34         else:
  35             return "{bdg-secondary}`适配状态未知`"
  36     r = []
  37     if is_api:
  38         r.append("{bdg-success}`本接口仅支持`")
  39     else:
  40         r.append("{bdg-success}`已适配`")
  41     for bsp in bsp_header_list:
  42         if bsp["url"].find(" "+tag+" ") >= 0 or bsp["url"].find(" "+tag+"\r") >= 0 or bsp["url"].find(" "+tag+"\n") >= 0:
  43             r.append("{bdg-primary}`" + bsp["name"] + "`")
  44     if len(r) > 1:
  45         return " ".join(r)
  46     else:
  47         return "{bdg-secondary}`适配状态未知`"
  48
  49 def make(path,modules,index_text):
  50     try:
  51         shutil.rmtree(path)
  52     except:
  53         pass
  54     os.mkdir(path)
  55     is_api = str(path).endswith("api/")
  56
  57     # 创建表格
  58     if is_api :
  59         doc = open(path+"supported.md", "w+",encoding='utf-8')
  60         doc.write("# 适配状态\n\n")
  61         doc.write("|BSP/库|简介")
  62         for bsp in bsp_header_list:
  63             doc.write("|" + bsp["name"])
  64         doc.write("|\n")
  65
  66         doc.write("|---|---")
  67         for bsp in bsp_header_list:
  68             doc.write("|---")
  69         doc.write("|\n")
  70
  71         for module in modules:
  72             name = module["module"]
  73             doc.write("|[{}]({}.md)|`{}`".format(name, name, module["summary"]))
  74             for bsp in bsp_header_list:
  75                 if len(module["tag"]) == 0 :
  76                     doc.write("|?")
  77                     continue
  78                 if is_supported(module["tag"], bsp) :
  79                     doc.write("|Y")
  80                 else:
  81                     doc.write("|X")
  82             doc.write("|\n")
  83         doc.close()
  84     doc = open(path+"index.md", "a+",encoding='utf-8')
  85     doc.write(index_text)
  86     # 创建toctree
  87     doc.write("\n\n请点击左侧列表，查看各个接口。如需搜索，请使用F5进行搜索。\n\n"+
  88                                                     "```{toctree}\n")
  89     if is_api:
  90         doc.write("supported\n")
  91     for module in modules:
  92         doc.write(module["module"]+"\n")
  93     doc.write("```\n")
  94     doc.close()
  95
  96     for module in modules:
  97         mdoc = open(path+module["module"]+".md", "a+",encoding='utf-8')
  98         mdoc.write("# "+module["module"]+" - "+module["summary"]+"\n\n")
  99
 100         #支持的芯片
 101         mdoc.write(get_tags(module["tag"]))
 102         mdoc.write("\n\n")
 103
 104         if len(module["url"]) > 0:
 105             mdoc.write("```{note}\n本页文档由[这个文件]("+module["url"]+")自动生成。如有错误，请提交issue或帮忙修改后pr，谢谢！\n```\n\n")
 106
 107         if len(module["demo"]) > 0:
 108             mdoc.write("```{tip}\n本库有专属demo，[点此链接查看"+module["module"]+"的demo例子]("+module["demo"]+")\n```\n")
 109         if len(module["video"]) > 0:
 110             mdoc.write("```{tip}\n本库还有视频教程，[点此链接查看]("+module["video"]+")\n```\n\n")
 111         else:
 112             mdoc.write("\n")
 113
 114         if len(module["usage"]) > 0:
 115             mdoc.write("**示例**\n\n")
 116             mdoc.write("```lua\n"+module["usage"]+"\n```\n\n")
 117
 118         if len(module["const"]) > 0:
 119             mdoc.write("## 常量\n\n")
 120             mdoc.write("|常量|类型|解释|\n|-|-|-|\n")
 121             for const in module["const"]:
 122                 mdoc.write("|"+const["var"].replace("|","\|")+"|"+const["type"].replace("|","\|")+"|"+const["summary"].replace("|","\|")+"|\n")
 123             mdoc.write("\n\n")
 124
 125
 126         for api in module["api"]:
 127             mdoc.write("## "+api["api"]+"\n\n")
 128
 129             #支持的芯片
 130             mdoc.write(get_tags(api["tag"], True))
 131             mdoc.write("\n\n")
 132
 133             mdoc.write(api["summary"]+"\n\n")
 134
 135             mdoc.write("**参数**\n\n")
 136             if len(api["args"]) > 0:
 137                 mdoc.write("|传入值类型|解释|\n|-|-|\n")
 138                 for arg in api["args"]:
 139                     mdoc.write("|"+arg["type"].replace("|","\|")+"|"+arg["summary"].replace("|","\|")+"|\n")
 140                 mdoc.write("\n")
 141             else:
 142                 mdoc.write("无\n\n")
 143
 144             mdoc.write("**返回值**\n\n")
 145             if len(api["return"]) > 0:
 146                 mdoc.write("|返回值类型|解释|\n|-|-|\n")
 147                 for arg in api["return"]:
 148                     mdoc.write("|"+arg["type"].replace("|","\|")+"|"+arg["summary"].replace("|","\|")+"|\n")
 149                 mdoc.write("\n")
 150             else:
 151                 mdoc.write("无\n\n")
 152
 153             mdoc.write("**例子**\n\n")
 154             if len(api["usage"]) == 0:
 155                 mdoc.write("无\n\n")
 156             else:
 157                 mdoc.write("```lua\n"+api["usage"]+"\n```\n\n")
 158
 159             mdoc.write("---\n\n")
 160
 161         mdoc.close()
 162
 163
 164
 165 def get_description(api):
 166     s = api["api"]+" - "+api["summary"]+"\n"
 167     if len(api["args"]) > 0:
 168         s = s + "传入值：\n"
 169         for arg in api["args"]:
 170             s  = s + arg["type"] + " " + arg["summary"]+"\n"
 171     if len(api["return"]) > 0:
 172         s = s + "返回值：\n"
 173         for arg in api["return"]:
 174             s  = s + arg["type"] + " " + arg["summary"]+"\n"
 175     if len(api["usage"]) > 0:
 176         s = s + "例子：\n" + api["usage"]
 177     return s