1#!/usr/bin/env python3 2import os, sys, getopt, re, pickle 3import subprocess 4 5class State: 6 SearchTitle = 0 7 SearchEndTitle = 1 8 SearchStartAPI = 2 9 SearchEndAPI = 3 10 DoneAPI = 4 11 12header_files = {} 13functions = {} 14typedefs = {} 15 16linenr = 0 17typedefFound = 0 18multiline_function_def = 0 19state = State.SearchStartAPI 20 21# if dash is used in api_header, the windmill theme will repeat the same API_TITLE twice in the menu (i.e: APIs/API_TITLE/API_TITLE) 22# if <h2> is used, this is avoided (i.e: APIs/API_TITLE), but reference {...} is not translated to HTML 23api_header = """ 24# API_TITLE API {#sec:API_LABEL_api} 25 26""" 27 28api_subheader = """ 29## API_TITLE API {#sec:API_LABEL_api} 30 31""" 32 33api_description = """ 34**FILENAME** DESCRIPTION 35 36""" 37 38code_ref = """GITHUB/FPATH#LLINENR""" 39 40def isEndOfComment(line): 41 return re.match('\s*\*/.*', line) 42 43def isStartOfComment(line): 44 return re.match('\s*\/\*/.*', line) 45 46def isTypedefStart(line): 47 return re.match('.*typedef\s+struct.*', line) 48 49def codeReference(fname, githuburl, filename_without_extension, filepath, linenr): 50 global code_ref 51 ref = code_ref.replace("GITHUB", githuburl) 52 ref = ref.replace("FPATH", filename_without_extension) 53 ref = ref.replace("LINENR", str(linenr)) 54 return ref 55 56def isTagAPI(line): 57 return re.match('(.*)(-\s*\')(APIs).*',line) 58 59def getSecondLevelIdentation(line): 60 indentation = "" 61 parts = re.match('(.*)(-\s*\')(APIs).*',line) 62 if parts: 63 # return double identation for the submenu 64 indentation = parts.group(1) + parts.group(1) + "- " 65 return indentation 66 67def filename_stem(filepath): 68 return os.path.splitext(os.path.basename(filepath))[0] 69 70def writeAPI(fout, fin, mk_codeidentation): 71 state = State.SearchStartAPI 72 73 for line in fin: 74 if state == State.SearchStartAPI: 75 parts = re.match('.*API_START.*',line) 76 if parts: 77 state = State.SearchEndAPI 78 continue 79 80 if state == State.SearchEndAPI: 81 parts = re.match('.*API_END.*',line) 82 if parts: 83 state = State.DoneAPI 84 continue 85 fout.write(mk_codeidentation + line) 86 continue 87 88 89 90def createIndex(fin, filename, api_filepath, api_title, api_label, githuburl): 91 global typedefs, functions 92 global linenr, multiline_function_def, typedefFound, state 93 94 95 for line in fin: 96 if state == State.DoneAPI: 97 continue 98 99 linenr = linenr + 1 100 101 if state == State.SearchStartAPI: 102 parts = re.match('.*API_START.*',line) 103 if parts: 104 state = State.SearchEndAPI 105 continue 106 107 if state == State.SearchEndAPI: 108 parts = re.match('.*API_END.*',line) 109 if parts: 110 state = State.DoneAPI 111 continue 112 113 if multiline_function_def: 114 function_end = re.match('.*;\n', line) 115 if function_end: 116 multiline_function_def = 0 117 continue 118 119 param = re.match(".*@brief.*", line) 120 if param: 121 continue 122 param = re.match(".*@param.*", line) 123 if param: 124 continue 125 param = re.match(".*@return.*", line) 126 if param: 127 continue 128 129 # search typedef struct begin 130 if isTypedefStart(line): 131 typedefFound = 1 132 133 # search typedef struct end 134 if typedefFound: 135 typedef = re.match('}\s*(.*);\n', line) 136 if typedef: 137 typedefFound = 0 138 typedefs[typedef.group(1)] = codeReference(typedef.group(1), githuburl, filename, api_filepath, linenr) 139 continue 140 141 ref_function = re.match('.*typedef\s+void\s+\(\s*\*\s*(.*?)\)\(.*', line) 142 if ref_function: 143 functions[ref_function.group(1)] = codeReference(ref_function.group(1), githuburl, filename, api_filepath, linenr) 144 continue 145 146 147 one_line_function_definition = re.match('(.*?)\s*\(.*\(*.*;\n', line) 148 if one_line_function_definition: 149 parts = one_line_function_definition.group(1).split(" "); 150 name = parts[len(parts)-1] 151 if len(name) == 0: 152 print(parts); 153 sys.exit(10) 154 functions[name] = codeReference( name, githuburl, filename, api_filepath, linenr) 155 continue 156 157 multi_line_function_definition = re.match('.(.*?)\s*\(.*\(*.*', line) 158 if multi_line_function_definition: 159 parts = multi_line_function_definition.group(1).split(" "); 160 161 name = parts[len(parts)-1] 162 if len(name) == 0: 163 print(parts); 164 sys.exit(10) 165 multiline_function_def = 1 166 functions[name] = codeReference(name, githuburl, filename, api_filepath, linenr) 167 168 169def findTitle(fin): 170 title = None 171 desc = "" 172 state = State.SearchTitle 173 174 for line in fin: 175 if state == State.SearchTitle: 176 if isStartOfComment(line): 177 continue 178 179 parts = re.match('.*(@title)(.*)', line) 180 if parts: 181 title = parts.group(2).strip() 182 state = State.SearchEndTitle 183 continue 184 185 if state == State.SearchEndTitle: 186 if (isEndOfComment(line)): 187 state = State.DoneAPI 188 break 189 190 parts = re.match('(\s*\*\s*)(.*\n)',line) 191 if parts: 192 desc = desc + parts.group(2) 193 return [title, desc] 194 195def main(argv): 196 global linenr, multiline_function_def, typedefFound, state 197 198 mk_codeidentation = " " 199 git_branch_name = "master" 200 btstackfolder = "../../" 201 githuburl_template = "https://github.com/bluekitchen/btstack/blob/" 202 githuburl = "master/src/" 203 markdownfolder = "docs-markdown/" 204 205 cmd = 'markdown_create_apis.py [-r <root_btstackfolder>] [-g <githuburl>] [-o <output_markdownfolder>]' 206 try: 207 opts, args = getopt.getopt(argv,"r:g:o:",["rfolder=","github=","ofolder="]) 208 except getopt.GetoptError: 209 print (cmd) 210 sys.exit(2) 211 for opt, arg in opts: 212 if opt == '-h': 213 print (cmd) 214 sys.exit() 215 elif opt in ("-r", "--rfolder"): 216 btstackfolder = arg 217 elif opt in ("-g", "--github"): 218 githuburl = arg 219 elif opt in ("-o", "--ofolder"): 220 markdownfolder = arg 221 222 apifile = markdownfolder + "appendix/apis.md" 223 # indexfile = markdownfolder + "api_index.md" 224 btstack_srcfolder = btstackfolder + "src/" 225 226 try: 227 output = subprocess.check_output("git symbolic-ref --short HEAD", stderr=subprocess.STDOUT, timeout=3, shell=True) 228 git_branch_name = output.decode().rstrip() 229 except subprocess.CalledProcessError as exc: 230 print('GIT branch name: failed to get, use default value \"%s\"" ', git_branch_name, exc.returncode, exc.output) 231 else: 232 print ('GIT branch name : %s' % git_branch_name) 233 234 githuburl = githuburl_template + git_branch_name 235 236 print ('BTstack src folder is : ' + btstack_srcfolder) 237 print ('API file is : ' + apifile) 238 print ('Github URL is : ' + githuburl) 239 240 # create a dictionary of header files {file_path : [title, description]} 241 # title and desctiption are extracted from the file 242 for root, dirs, files in os.walk(btstack_srcfolder, topdown=True): 243 for f in files: 244 if not f.endswith(".h"): 245 continue 246 247 if not root.endswith("/"): 248 root = root + "/" 249 250 header_filepath = root + f 251 252 with open(header_filepath, 'rt') as fin: 253 [header_title, header_desc] = findTitle(fin) 254 255 if header_title: 256 header_files[header_filepath] = [header_title, header_desc] 257 else: 258 print("No @title flag found. Skip %s" % header_filepath) 259 260 # create an >md file, for each header file in header_files dictionary 261 for header_filepath in sorted(header_files.keys()): 262 filename = str(header_filepath) 263 filename = filename.split("../../")[1] 264 265 filename_without_extension = filename_stem(header_filepath) # file name without .h 266 filetitle = header_files[header_filepath][0] 267 description = header_files[header_filepath][1] 268 269 if len(description) > 1: 270 description = ": " + description 271 272 header_description = api_description.replace("FILENAME", filename).replace("DESCRIPTION", description) 273 274 header_title = api_header.replace("API_TITLE", filetitle).replace("API_LABEL", filename_without_extension) 275 markdown_filepath = markdownfolder + "appendix/" + filename_without_extension + ".md" 276 277 with open(header_filepath, 'rt') as fin: 278 with open(markdown_filepath, 'wt') as fout: 279 fout.write(header_title) 280 fout.write(header_description) 281 writeAPI(fout, fin, mk_codeidentation) 282 283 with open(header_filepath, 'rt') as fin: 284 linenr = 0 285 typedefFound = 0 286 multiline_function_def = 0 287 state = State.SearchStartAPI 288 createIndex(fin, filename, markdown_filepath, header_title, filename_without_extension, githuburl) 289 290 # add API list to the navigation menu 291 with open("mkdocs-temp.yml", 'rt') as fin: 292 with open("mkdocs.yml", 'wt') as fout: 293 for line in fin: 294 fout.write(line) 295 296 if not isTagAPI(line): 297 continue 298 299 identation = getSecondLevelIdentation(line) 300 301 for header_filepath in sorted(header_files.keys()): 302 header_title = os.path.basename(header_filepath) 303 markdown_reference = "appendix/" + filename_stem(header_filepath) + ".md" 304 305 fout.write(identation + "'" + header_title + "': " + markdown_reference + "\n") 306 307 308 # create mkdocs-latex.yml with single appendix/apis.md reference for pdf generation 309 with open("mkdocs-temp.yml", 'rt') as fin: 310 with open("mkdocs-latex.yml", 'wt') as fout: 311 for line in fin: 312 if not isTagAPI(line): 313 fout.write(line) 314 continue 315 316 fout.write(" - 'APIs': appendix/apis.md\n") 317 318 # create single appendix/apis.md file for pdf generation 319 markdown_filepath = markdownfolder + "appendix/apis.md" 320 with open(markdown_filepath, 'wt') as fout: 321 fout.write("\n# APIs\n\n") 322 for header_filepath in sorted(header_files.keys()): 323 filename = os.path.basename(header_filepath) 324 filename_without_extension = filename_stem(header_filepath) # file name without 325 filetitle = header_files[header_filepath][0] 326 327 description = header_files[header_filepath][1] 328 329 if len(description) > 1: 330 description = ": " + description 331 332 header_description = api_description.replace("FILENAME", filename).replace("DESCRIPTION", description) 333 334 subheader_title = api_subheader.replace("API_TITLE", filetitle).replace("API_LABEL", filename_without_extension) 335 with open(header_filepath, 'rt') as fin: 336 fout.write(subheader_title) 337 fout.write(header_description) 338 writeAPI(fout, fin, mk_codeidentation) 339 340 341 references = functions.copy() 342 references.update(typedefs) 343 344 # with open(indexfile, 'w') as fout: 345 # for function, reference in references.items(): 346 # fout.write("[" + function + "](" + reference + ")\n") 347 348 pickle.dump(references, open("references.p", "wb" ) ) 349 350if __name__ == "__main__": 351 main(sys.argv[1:]) 352