docs: cleanup build

doc/manual/Makefile

@@ -1,43 +1,46 @@
-all: update_docs_and_apis html pdf
+all: update_apis_and_listings html pdf
 
 html:
-	rm -rf docs_tmp
 	rm -rf docs_final
-	cp -r docs docs_tmp
 	cp -r docs docs_final
+	# create docs/ports/existing_ports.md
 	./ports2markdown.py
+	# docs -> docs_final
 	./markdown2mkdocs.py
-	rm -rf docs_tmp
 	mkdocs build --clean
 	./mkdocs2html.py
 
 pdf:
 	mkdir -p latex
 	cp -r docs/picts latex
+	# create docs/ports/existing_ports.md
 	./ports2markdown.py
-	./markdown2pdf.py
+	# create latex/btstack_generated.md -> latex/btstack_final.tex
+	./markdown2tex.py
 	cp btstack_gettingstarted.tex latex
 	cd latex && pdflatex btstack_gettingstarted.tex && pdflatex btstack_gettingstarted.tex
 	mv latex/btstack_gettingstarted.pdf btstack.pdf
 	rm -rf latex tmp
 
 
-preview: update_docs_and_apis html
+preview: update_apis_and_listings html
 	# race condition, open browser before startnig MKdocs
 	open http://127.0.0.1:8000
 	mkdocs serve
 
-update_docs_and_apis:
+update_apis_and_listings:
 	sed -e "s|../doc/manual/docs/||g" ../../chipset/README.md > docs/chipsets.md
 	rm -rf tmp
 	mkdir tmp
+	# create docs/appendix/apis.md
 	./update_apis.py	
+	# create docs/examples/examples.md
 	./update_listings.py
 
 clean:
 	rm -rf docs_final tmp btstack *.pdf latex/btstack_generated.* latex/btstack_final.tex
 	rm -rf docs/appendix/apis.md docs/appendix/index.md docs/examples/examples.md docs/chipsets.md
-	rm -rf docs_tmp latex btstack help
+	rm -rf latex btstack help
 	
 
 	

doc/manual/markdown2mkdocs.py

@@ -9,9 +9,9 @@ def insert_anchor(mdout, reference):
 def insert_reference(mdout, text, link):
     mdout.write("")
 
-def process_sections(temp_file, dest_file):
+def process_sections(source_file, dest_file):
     with open(dest_file, 'w') as mdout:
-        with open(temp_file, 'r') as mdin:
+        with open(source_file, 'r') as mdin:
             for line in mdin:
                 section = re.match('(#+.*){#(sec:.*)}',line)
                 if section:
@@ -20,12 +20,9 @@ def process_sections(temp_file, dest_file):
                 else:
                     mdout.write(line)
                 
-    shutil.copyfile(dest_file, temp_file)
-    return
-
-def process_figures(temp_file, dest_file):
+def process_figures(source_file, dest_file):
     with open(dest_file, 'w') as mdout:
-        with open(temp_file, 'r') as mdin:
+        with open(source_file, 'r') as mdin:
             for line in mdin:
                 # detect figure
                 figure = re.match('\s*(\!.*)({#(fig:.*)})',line)
@@ -38,12 +35,10 @@ def process_figures(temp_file, dest_file):
                         md_reference = "[below](#"+figure_ref.group(2)+")"
                         line = line.replace(figure_ref.group(1), md_reference) 
                     mdout.write(line)
-    shutil.copyfile(dest_file, temp_file)
-    return
 
-def process_tables(temp_file, dest_file):
+def process_tables(source_file, dest_file):
     with open(dest_file, 'w') as mdout:
-        with open(temp_file, 'r') as mdin:
+        with open(source_file, 'r') as mdin:
             for line in mdin:
                 # detect table
                 table = re.match('\s*(Table:.*)({#(tbl:.*)})',line)
@@ -56,13 +51,11 @@ def process_tables(temp_file, dest_file):
                         md_reference = "[below](#"+table_ref.group(2)+")"
                         line = line.replace(table_ref.group(1), md_reference) 
                     mdout.write(line)
-    shutil.copyfile(dest_file, temp_file)
-    return
 
 
-def process_listings(temp_file, dest_file):
+def process_listings(source_file, dest_file):
     with open(dest_file, 'w') as mdout:
-        with open(temp_file, 'r') as mdin:
+        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)
@@ -72,14 +65,10 @@ def process_listings(temp_file, dest_file):
                     mdout.write("\n")
                 else:
                     mdout.write(line)
-    shutil.copyfile(dest_file, temp_file)
-    return
-
 
 
 def main(argv):
     md_template = "docs"
-    md_temp = "docs_tmp"
     md_final = "docs_final"
     yml_file = "mkdocs.yml"
     
@@ -87,13 +76,12 @@ def main(argv):
         doc = yaml.load(yin)
         for page in doc["pages"]:
             source_file = md_template +"/"+ page[0]
-            temp_file   = md_temp +"/"+ page[0]
             dest_file   = md_final +"/"+ page[0]
             
-            process_sections(temp_file, dest_file)
-            process_figures(temp_file, dest_file)
-            process_tables(temp_file, dest_file)
-            process_listings(temp_file, dest_file)
+            process_sections(source_file, dest_file)
+            process_figures(source_file, dest_file)
+            process_tables(source_file, dest_file)
+            process_listings(source_file, dest_file)
 
 
 if __name__ == "__main__":

doc/manual/markdown2tex.py

@@ -47,6 +47,11 @@ def fix_appendix_pagebreak(line):
         line = "\leavevmode\pagebreak\n" + line
     return line
 
+def fix_tightlist(line):
+    if 'tightlist' in line:
+        return ''
+    else:
+        return line
 
 def main(argv):
     docs_folder = "docs"
@@ -92,6 +97,7 @@ def main(argv):
                 line = fix_listing_hyperref_into_ref(line)
                 line = fix_figure_width_and_type(line)
                 line = fix_appendix_pagebreak(line)
+                line = fix_tightlist(line)
                 aout.write(line)