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(r'\s*\*/.*', line) 42 43def isStartOfComment(line): 44 return re.match(r'\s*\/\*/.*', line) 45 46def isTypedefStart(line): 47 return re.match(r'.*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(r'(.*)(-\s*\')(APIs).*',line) 58 59def getSecondLevelIdentation(line): 60 indentation = "" 61 parts = re.match(r'(.*)(-\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(r'}\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(r'.*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(r'(.*?)\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 # ignore typedef for callbacks 155 if parts[0] == 'typedef': 156 continue 157 functions[name] = codeReference( name, githuburl, filename, api_filepath, linenr) 158 continue 159 160 multi_line_function_definition = re.match(r'.(.*?)\s*\(.*\(*.*', line) 161 if multi_line_function_definition: 162 parts = multi_line_function_definition.group(1).split(" "); 163 164 name = parts[len(parts)-1] 165 if len(name) == 0: 166 print(parts); 167 sys.exit(10) 168 multiline_function_def = 1 169 functions[name] = codeReference(name, githuburl, filename, api_filepath, linenr) 170 171 172def findTitle(fin): 173 title = None 174 desc = "" 175 state = State.SearchTitle 176 177 for line in fin: 178 if state == State.SearchTitle: 179 if isStartOfComment(line): 180 continue 181 182 parts = re.match(r'.*(@title)(.*)', line) 183 if parts: 184 title = parts.group(2).strip() 185 state = State.SearchEndTitle 186 continue 187 188 if state == State.SearchEndTitle: 189 if (isEndOfComment(line)): 190 state = State.DoneAPI 191 break 192 193 parts = re.match(r'(\s*\*\s*)(.*\n)',line) 194 if parts: 195 desc = desc + parts.group(2) 196 return [title, desc] 197 198def main(argv): 199 global linenr, multiline_function_def, typedefFound, state 200 201 mk_codeidentation = " " 202 git_branch_name = "master" 203 btstackfolder = "../../" 204 githuburl_template = "https://github.com/bluekitchen/btstack/blob/" 205 githuburl = "master/src/" 206 markdownfolder = "docs-markdown/" 207 208 cmd = 'markdown_create_apis.py [-r <root_btstackfolder>] [-g <githuburl>] [-o <output_markdownfolder>]' 209 try: 210 opts, args = getopt.getopt(argv,"r:g:o:",["rfolder=","github=","ofolder="]) 211 except getopt.GetoptError: 212 print (cmd) 213 sys.exit(2) 214 for opt, arg in opts: 215 if opt == '-h': 216 print (cmd) 217 sys.exit() 218 elif opt in ("-r", "--rfolder"): 219 btstackfolder = arg 220 elif opt in ("-g", "--github"): 221 githuburl = arg 222 elif opt in ("-o", "--ofolder"): 223 markdownfolder = arg 224 225 apifile = markdownfolder + "appendix/apis.md" 226 # indexfile = markdownfolder + "api_index.md" 227 btstack_srcfolder = btstackfolder + "src/" 228 229 try: 230 output = subprocess.check_output("git symbolic-ref --short HEAD", stderr=subprocess.STDOUT, timeout=3, shell=True) 231 git_branch_name = output.decode().rstrip() 232 except subprocess.CalledProcessError as exc: 233 print('GIT branch name: failed to get, use default value \"%s\"" ', git_branch_name, exc.returncode, exc.output) 234 else: 235 print ('GIT branch name : %s' % git_branch_name) 236 237 githuburl = githuburl_template + git_branch_name 238 239 print ('BTstack src folder is : ' + btstack_srcfolder) 240 print ('API file is : ' + apifile) 241 print ('Github URL is : ' + githuburl) 242 243 # create a dictionary of header files {file_path : [title, description]} 244 # title and desctiption are extracted from the file 245 for root, dirs, files in os.walk(btstack_srcfolder, topdown=True): 246 for f in files: 247 if not f.endswith(".h"): 248 continue 249 250 if not root.endswith("/"): 251 root = root + "/" 252 253 header_filepath = root + f 254 255 with open(header_filepath, 'rt') as fin: 256 [header_title, header_desc] = findTitle(fin) 257 258 if header_title: 259 header_files[header_filepath] = [header_title, header_desc] 260 else: 261 print("No @title flag found. Skip %s" % header_filepath) 262 263 # create an >md file, for each header file in header_files dictionary 264 for header_filepath in sorted(header_files.keys()): 265 filename = str(header_filepath) 266 filename = filename.split("../../")[1] 267 268 filename_without_extension = filename_stem(header_filepath) # file name without .h 269 filetitle = header_files[header_filepath][0] 270 description = header_files[header_filepath][1] 271 272 if len(description) > 1: 273 description = ": " + description 274 275 header_description = api_description.replace("FILENAME", filename).replace("DESCRIPTION", description) 276 277 header_title = api_header.replace("API_TITLE", filetitle).replace("API_LABEL", filename_without_extension) 278 markdown_filepath = markdownfolder + "appendix/" + filename_without_extension + ".md" 279 280 with open(header_filepath, 'rt') as fin: 281 with open(markdown_filepath, 'wt') as fout: 282 fout.write(header_title) 283 fout.write(header_description) 284 writeAPI(fout, fin, mk_codeidentation) 285 286 with open(header_filepath, 'rt') as fin: 287 linenr = 0 288 typedefFound = 0 289 multiline_function_def = 0 290 state = State.SearchStartAPI 291 createIndex(fin, filename, markdown_filepath, header_title, filename_without_extension, githuburl) 292 293 # add API list to the navigation menu 294 with open("mkdocs-temp.yml", 'rt') as fin: 295 with open("mkdocs.yml", 'wt') as fout: 296 for line in fin: 297 fout.write(line) 298 299 if not isTagAPI(line): 300 continue 301 302 identation = getSecondLevelIdentation(line) 303 304 for header_filepath in sorted(header_files.keys()): 305 header_title = os.path.basename(header_filepath) 306 markdown_reference = "appendix/" + filename_stem(header_filepath) + ".md" 307 308 fout.write(identation + "'" + header_title + "': " + markdown_reference + "\n") 309 310 311 # create mkdocs-latex.yml with single appendix/apis.md reference for pdf generation 312 with open("mkdocs-temp.yml", 'rt') as fin: 313 with open("mkdocs-latex.yml", 'wt') as fout: 314 for line in fin: 315 if not isTagAPI(line): 316 fout.write(line) 317 continue 318 319 fout.write(" - 'APIs': appendix/apis.md\n") 320 321 # create single appendix/apis.md file for pdf generation 322 markdown_filepath = markdownfolder + "appendix/apis.md" 323 with open(markdown_filepath, 'wt') as fout: 324 fout.write("\n# APIs\n\n") 325 for header_filepath in sorted(header_files.keys()): 326 filename = os.path.basename(header_filepath) 327 filename_without_extension = filename_stem(header_filepath) # file name without 328 filetitle = header_files[header_filepath][0] 329 330 description = header_files[header_filepath][1] 331 332 if len(description) > 1: 333 description = ": " + description 334 335 header_description = api_description.replace("FILENAME", filename).replace("DESCRIPTION", description) 336 337 subheader_title = api_subheader.replace("API_TITLE", filetitle).replace("API_LABEL", filename_without_extension) 338 with open(header_filepath, 'rt') as fin: 339 fout.write(subheader_title) 340 fout.write(header_description) 341 writeAPI(fout, fin, mk_codeidentation) 342 343 344 references = functions.copy() 345 references.update(typedefs) 346 347 # with open(indexfile, 'w') as fout: 348 # for function, reference in references.items(): 349 # fout.write("[" + function + "](" + reference + ")\n") 350 351 pickle.dump(references, open("references.p", "wb" ) ) 352 353if __name__ == "__main__": 354 main(sys.argv[1:]) 355