doc: fix preprocessing before mkdocs

doc/manual/Makefile

@@ -1,15 +1,14 @@
 all: update_apis_and_listings html pdf
 
-html:
+html: 
 	# create docs/ports/existing_ports.md + adds images
 	./ports2markdown.py
 	# re-create docs_final
-	rm -rf docs_final
 	cp -r docs docs_final
 	# docs -> docs_final
 	./markdown2mkdocs.py
 	mkdocs build --clean
-	./mkdocs2html.py
+	# ./mkdocs2html.py
 
 pdf:
 	mkdir -p latex

doc/manual/markdown2mkdocs.py

@@ -3,69 +3,70 @@
 import sys, os, shutil
 import re, yaml
 
+# helper to write anchors and references
 def insert_anchor(mdout, reference):
-    mdout.write("<a name=\"" + reference + "\"></a>\n\n")
+    anchor = "<a name=\"" + reference + "\"></a>\n\n"
+    mdout.write(anchor)
 
 def insert_reference(mdout, text, link):
     mdout.write("")
 
-def process_sections(source_file, dest_file):
-    with open(dest_file, 'w') as mdout:
-        with open(source_file, 'r') as mdin:
-            for line in mdin:
-                section = re.match('(#+.*){#(sec:.*)}',line)
-                if section:
-                    insert_anchor(mdout, section.group(2))
-                    mdout.write(section.group(1)+"\n")
-                else:
-                    mdout.write(line)
-                
-def process_figures(source_file, dest_file):
-    with open(dest_file, 'w') as mdout:
-        with open(source_file, 'r') as mdin:
-            for line in mdin:
-                # detect figure
-                figure = re.match('\s*(\!.*)({#(fig:.*)})',line)
-                if figure:
-                    insert_anchor(mdout, figure.group(3))
-                    mdout.write(figure.group(1)+"\n")
-                else:
-                    figure_ref = re.match('.*({@(fig:.*)})',line)
-                    if figure_ref:
-                        md_reference = "[below](#"+figure_ref.group(2)+")"
-                        line = line.replace(figure_ref.group(1), md_reference) 
-                    mdout.write(line)
+# handlers for various elements
+def process_section(mdin, mdout, line):
+    section = re.match('(#+.*){#(sec:.*)}',line)
+    if section:
+        insert_anchor(mdout, section.group(2))
+        mdout.write(section.group(1)+"\n")
+        line = ''
+    return line
 
-def process_tables(source_file, dest_file):
-    with open(dest_file, 'w') as mdout:
-        with open(source_file, 'r') as mdin:
-            for line in mdin:
-                # detect table
-                table = re.match('\s*(Table:.*)({#(tbl:.*)})',line)
-                if table:
-                    insert_anchor(mdout, table.group(3))
-                    mdout.write(table.group(1)+"\n")
-                else:
-                    table_ref = re.match('.*({@(tbl:.*)})',line)
-                    if table_ref:
-                        md_reference = "[below](#"+table_ref.group(2)+")"
-                        line = line.replace(table_ref.group(1), md_reference) 
-                    mdout.write(line)
+def process_figure(mdin, mdout, line):
+    # detect figure
+    figure = re.match('\s*(\!.*)({#(fig:.*)})',line)
+    if figure:
+        insert_anchor(mdout, figure.group(3))
+        mdout.write(figure.group(1)+"\n")
+        line = ''
+    return line
 
+def process_fig_ref(mdin, mdout, line):
+    # detect figure reference
+    figure_ref = re.match('.*({@(fig:.*)})',line)
+    if figure_ref:
+        md_reference = "[below](#"+figure_ref.group(2)+")"
+        line = line.replace(figure_ref.group(1), md_reference) 
+        mdout.write(line)
+        line = ''
+    return line
 
-def process_listings(source_file, dest_file):
-    with open(dest_file, 'w') as mdout:
-        with open(source_file, 'r') as mdin:
-            for line in mdin:
-                listing_start = re.match('.*{#(lst:.*)\s+.c\s+.*',line)
-                listing_end = re.match('\s*~~~~\s*\n',line)
-                if listing_start:
-                    insert_anchor(mdout, listing_start.group(1))
-                elif listing_end:
-                    mdout.write("\n")
-                else:
-                    mdout.write(line)
+def process_table(mdin, mdout, line):
+    # detect table
+    table = re.match('\s*(Table:.*)({#(tbl:.*)})',line)
+    if table:
+        insert_anchor(mdout, table.group(3))
+        mdout.write(table.group(1)+"\n")
+        line = ''
+    return line
 
+def process_tbl_ref(mdin, mdout, line):
+    table_ref = re.match('.*({@(tbl:.*)})',line)
+    if table_ref:
+        md_reference = "[below](#"+table_ref.group(2)+")"
+        line = line.replace(table_ref.group(1), md_reference) 
+        mdout.write(line)
+        line = ''
+    return line
+
+def process_listing(mdin, mdout, line):
+    listing_start = re.match('.*{#(lst:.*)\s+.c\s+.*',line)
+    listing_end   = re.match('\s*~~~~\s*\n',line)
+    if listing_start:
+        insert_anchor(mdout, listing_start.group(1))
+        line = ''
+    elif listing_end:
+        mdout.write("\n")
+        line = ''
+    return line
 
 def main(argv):
     md_template = "docs"
@@ -77,12 +78,29 @@ def main(argv):
         for page in doc["pages"]:
             source_file = md_template +"/"+ page[0]
             dest_file   = md_final +"/"+ page[0]
-            
-            process_sections(source_file, dest_file)
-            process_figures(source_file, dest_file)
-            process_tables(source_file, dest_file)
-            process_listings(source_file, dest_file)
-
+            print("Processing %s -> %s" % (source_file, dest_file))
+            with open(dest_file, 'w') as mdout:
+                with open(source_file, 'r') as mdin:
+                    for line in mdin:
+                        line = process_section(mdin, mdout, line)
+                        if len(line) == 0:
+                            continue
+                        line = process_figure(mdin, mdout, line)
+                        if len(line) == 0:
+                            continue
+                        line = process_fig_ref(mdin, mdout, line)
+                        if len(line) == 0:
+                            continue
+                        line = process_table(mdin, mdout, line)
+                        if len(line) == 0:
+                            continue
+                        line = process_tbl_ref(mdin, mdout, line)
+                        if len(line) == 0:
+                            continue
+                        line = process_listing(mdin, mdout, line)
+                        if len(line) == 0:
+                            continue
+                        mdout.write(line)
 
 if __name__ == "__main__":
    main(sys.argv[1:])