xref: /btstack/doc/manual/markdown_update_references.py (revision b45b7749fd0a3efec18073ae84f893078d0216d0) 
1#!/usr/bin/env python3
2
3import sys, os, shutil, getopt
4import re, yaml
5
6# helper to write anchors and references
7def insert_anchor(mdout, reference):
8    anchor = "<a name=\"" + reference + "\"></a>\n\n"
9    mdout.write(anchor)
10
11def insert_reference(mdout, text, link):
12    mdout.write("")
13
14# handlers for various elements
15def process_section(mdin, mdout, line):
16    section = re.match('(#+.*){#(sec:.*)}',line)
17    if section:
18        insert_anchor(mdout, section.group(2))
19        mdout.write(section.group(1)+"\n")
20        line = ''
21    return line
22
23def process_figure(mdin, mdout, line):
24    # detect figure
25    figure = re.match('\s*(\!.*)({#(fig:.*)})',line)
26    if figure:
27        insert_anchor(mdout, figure.group(3))
28        mdout.write(figure.group(1)+"\n")
29        line = ''
30    return line
31
32def process_fig_ref(mdin, mdout, line):
33    # detect figure reference
34    figure_ref = re.match('.*({@(fig:.*)})',line)
35    if figure_ref:
36        md_reference = "[below](#"+figure_ref.group(2)+")"
37        line = line.replace(figure_ref.group(1), md_reference)
38        mdout.write(line)
39        line = ''
40    return line
41
42def process_table(mdin, mdout, line):
43    # detect table
44    table = re.match('\s*(Table:.*)({#(tbl:.*)})',line)
45    if table:
46        insert_anchor(mdout, table.group(3))
47        mdout.write(table.group(1)+"\n")
48        line = ''
49    return line
50
51def process_tbl_ref(mdin, mdout, line):
52    table_ref = re.match('.*({@(tbl:.*)})',line)
53    if table_ref:
54        md_reference = "[below](#"+table_ref.group(2)+")"
55        line = line.replace(table_ref.group(1), md_reference)
56        mdout.write(line)
57        line = ''
58    return line
59
60def process_listing(mdin, mdout, line):
61    listing_start = re.match('.*{#(lst:.*)\s+.c\s+.*',line)
62    listing_end   = re.match('\s*~~~~\s*\n',line)
63    if listing_start:
64        insert_anchor(mdout, listing_start.group(1))
65        line = ''
66    elif listing_end:
67        mdout.write("\n")
68        line = ''
69    return line
70
71def process_file(mk_file, markdownfolder, mkdocsfolder):
72    source_file = markdownfolder +"/"+ mk_file
73    dest_file   = mkdocsfolder +"/"+ mk_file
74    # print("Processing %s -> %s" % (source_file, dest_file))
75
76    with open(dest_file, 'wt') as mdout:
77        with open(source_file, 'rt') as mdin:
78            for line in mdin:
79                line = process_section(mdin, mdout, line)
80                if len(line) == 0:
81                    continue
82                line = process_figure(mdin, mdout, line)
83                if len(line) == 0:
84                    continue
85                line = process_fig_ref(mdin, mdout, line)
86                if len(line) == 0:
87                    continue
88                line = process_table(mdin, mdout, line)
89                if len(line) == 0:
90                    continue
91                line = process_tbl_ref(mdin, mdout, line)
92                if len(line) == 0:
93                    continue
94                line = process_listing(mdin, mdout, line)
95                if len(line) == 0:
96                    continue
97                mdout.write(line)
98
99def main(argv):
100    markdownfolder = "docs-markdown/"
101    mkdocsfolder = "docs/"
102
103    cmd = 'markdown_update_references.py [-i <markdownfolder>] [-o <mkdocsfolder>] '
104
105    try:
106        opts, args = getopt.getopt(argv,"i:o:",["ifolder=","ofolder="])
107    except getopt.GetoptError:
108        print (cmd)
109        sys.exit(2)
110    for opt, arg in opts:
111        if opt == '-h':
112            print (cmd)
113            sys.exit()
114        elif opt in ("-i", "--ifolder"):
115            markdownfolder = arg
116        elif opt in ("-o", "--ofolder"):
117            mkdocsfolder = arg
118
119    yml_file = "mkdocs.yml"
120
121    with open(yml_file, 'r') as yin:
122        doc = yaml.load(yin, Loader=yaml.SafeLoader)
123
124        # page is either:
125        # - {title: filepath} dictionary for a direcr yml reference (e.g.  - 'Welcome': index.md), or
126        # - {navigation_group_title: [{title: filepath}, ...] } dictionary for a navigation group
127        for page in doc["nav"]:
128
129            # navigation_group_filepath is either:
130            # - filepath string for a direcr yml reference (e.g.  - 'Welcome': index.md), or
131            # - list of [{title: filepath}, ...] dictionaries for each item in navigation group
132            navigation_group_filepath = list(page.values())[0]
133
134            if type(navigation_group_filepath) == str:
135                process_file(navigation_group_filepath, markdownfolder, mkdocsfolder)
136                continue
137
138            if type(navigation_group_filepath) == list:
139                for file_description_dict in navigation_group_filepath:
140                    filepath = list(file_description_dict.values())[0]
141                    process_file(filepath, markdownfolder, mkdocsfolder)
142                continue
143
144
145if __name__ == "__main__":
146   main(sys.argv[1:])
147