doc: cleanup build

chipset/README.md

@@ -6,7 +6,7 @@ In this chapter, we first explain how Bluetooth chipsets are connected physicall
 
 The communication between a Host (a computer or an MCU) and a Host Controller (the actual Bluetooth chipset) follows the Host Controller Interface (HCI), see {@fig:HostChipsetConnection}. HCI defines how commands, events, asynchronous and synchronous data packets are exchanged. Asynchronous packets (ACL) are used for data transfer, while synchronous packets (SCO) are used for Voice with the Headset and the Hands-Free Profiles.
 
-![Host Controller to Host connection](../doc/manual/docs/picts/host_chipset_connection.png){#fig:HostChipsetConnection}
+![Host Controller to Host connection](../doc/manual/docs-template/picts/host_chipset_connection.png){#fig:HostChipsetConnection}
 
 ### HCI H2
 On desktop-class computers incl. laptops, USB is mainly used as HCI transport layer. For USB Bluetooth chipsets, there is little variation: most USB dongles on the market currently contain a Broadcom BCM20702 or a CSR 851x chipset. It is also called H2.

doc/manual/Makefile

@@ -1,14 +1,58 @@
-all: update_content html pdf
+GITHUB_URL = "https://github.com/bluekitchen/btstack/tree/"
+BTSTACK_FOLDER = ../../
+INTRO_FOLDER = docs-intro/
+MARKDOWN_FOLDER = docs-markdown/
+MKDOCS_FOLDER = docs/
+HTML_FOLDER = btstack/
 
-html: 
+all: html pdf
-	# docs -> docs_final
+
-	./markdown2mkdocs.py
+docs-markdown:
-	# generate HTML
+	# create new docs_markdown
+	rm -rf docs-markdown
+	cp -r  docs-template docs-markdown
+	mkdir  docs-markdown/examples
+	mkdir  docs-markdown/ports
+
+	# create mkdocs.yml
+	./update_mkdocs_yml.sh
+	
+	# following should create files in docs-markdown
+
+	# Use chipsets/readme as chipsets.md
+	sed -e "s|../doc/manual/docs-template/||g" ../../chipset/README.md > docs-markdown/chipsets.md
+
+	# create docs-markdown/appendix/apis.md
+	# create docs-markdown/api_index.md
+	# create docs-markdown/references.p
+	./update_apis.py -r ${BTSTACK_FOLDER} -g ${GITHUB_URL} -o ${MARKDOWN_FOLDER}
+
+	# create docs-markdown/examples/examples.md
+	./update_listings.py -r ${BTSTACK_FOLDER} -t ${INTRO_FOLDER} -o ${MARKDOWN_FOLDER}
+
+	# create docs-markdown/ports/existing_ports.md
+	./ports2markdown.py -r ${BTSTACK_FOLDER} -t ${INTRO_FOLDER} -o ${MARKDOWN_FOLDER}
+
+	# create docs-markdown/gatt_clients.md and  docs-template/gatt_services.md
+	./update_gatt_services.py -r ${BTSTACK_FOLDER} -t ${INTRO_FOLDER} -o ${MARKDOWN_FOLDER}
+
+docs: docs-markdown 
+	# create new docs_final
+	rm -rf docs
+	cp -r  docs-markdown docs
+
+	# docs-markdown -> docs
+	./markdown2mkdocs.py  -i ${MARKDOWN_FOLDER} -o ${MKDOCS_FOLDER} 
+	
+
+html: docs
+	# generate HTML into btstack folder
 	mkdocs build --clean
-	# post-process HTML
+	
-	./mkdocs2html.py
+	# post-process HTML using docs-markdown/references.p 
+	./mkdocs2html.py -i ${MARKDOWN_FOLDER} -o ${HTML_FOLDER}
 
-pdf:
+pdf: docs
 	rm -rf latex
 	mkdir -p latex
 	cp -r docs/picts latex
@@ -20,34 +64,13 @@ pdf:
 	cd latex && pdflatex btstack_gettingstarted.tex && pdflatex btstack_gettingstarted.tex
 	mv latex/btstack_gettingstarted.pdf btstack.pdf
 
-preview: update_content html
+preview: docs
 	# race condition, open browser before starting MKdocs server
 	open http://127.0.0.1:8010
 	mkdocs serve -a localhost:8010
 
-update_content:
-	sed -e "s|../doc/manual/docs-template/||g" ../../chipset/README.md > docs-template/chipsets.md
-	rm -rf tmp
-	mkdir tmp
-	# create mkdocs.yml
-	./update_mkdocs_yml.sh
-	# create docs-template/appendix/apis.md
-	./update_apis.py	
-	# create docs-template/examples/examples.md
-	./update_listings.py
-	# create docs-template/ports/existing_ports.md
-	./ports2markdown.py
-	# create docs-template/gatt_clients.md and  docs-template/gatt_services.md
-	./update_gatt_services.py
-	# re-create docs_final
-	rm -rf docs
-	cp -r docs-template docs
-
 clean:
-	rm -rf docs tmp btstack *.pdf latex/btstack_generated.* latex/btstack_final.tex mkdocs.yml
+	rm -rf docs-markdown docs tmp btstack *.pdf latex/btstack_generated.* latex/btstack_final.tex mkdocs.yml
-	rm -rf docs-template/appendix/apis.md docs-template/examples/examples.md docs-template/chipsets.md
-	rm -rf docs-template/gatt_clients.md docs-template/gatt_services.md 
-	rm -rf api_index.md
 	rm -rf latex btstack help
 	
 

doc/manual/docs-template/docs/.gitignore

@@ -1,2 +0,0 @@
-gatt_clients.md
-gatt_services.md

doc/manual/docs-template/docs/appendix/.gitignore

@@ -1,2 +0,0 @@
-apis.md
-index.md

doc/manual/docs-template/docs/btstack.css

@@ -1,2 +0,0 @@
-a.toctree-l3 { display: none; }
-a.toctree-l4 { display: none; }

doc/manual/docs-template/docs/examples/.gitignore

@@ -1,2 +0,0 @@
-examples.md
-generated.md

doc/manual/docs-template/docs/ports/.gitignore

@@ -1,25 +0,0 @@
-existing_ports.md
-ATWILC3000-Breakout.jpg
-EM9304DVK.jpg
-apollo2-em9304
-esp32
-gadget-zero
-ios
-libopencm3
-libusb
-max32630-fthr
-pic32-harmony
-posix-h4-atwilc3000
-posix-h4-da14581
-posix-h4-zephyr
-samv71-xplained-atwilc3000
-setup-bluetooth-audio-devkit.jpg
-setup-stlc2500d.jpg
-setup-wl1835.jpg
-setup.jpg
-sketch.jpg
-stm32-f103rb-nucleo
-stm32-f4discovery-cc256x
-stm32-l053r8-em9304
-windows-winusb
-*.jpg

doc/manual/markdown2mkdocs.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-import sys, os, shutil
+import sys, os, shutil, getopt
 import re, yaml
 
 # helper to write anchors and references
@@ -69,16 +69,33 @@ def process_listing(mdin, mdout, line):
     return line
 
 def main(argv):
-    md_template = "docs-template"
+    markdownfolder = "docs-markdown/"
-    md_final = "docs"
+    mkdocsfolder = "docs/"
+
+    cmd = 'markdown2mkdocs.py [-i <markdownfolder>] [-o <mkdocsfolder>] '
+
+    try:
+        opts, args = getopt.getopt(argv,"i:o:",["ifolder=","ofolder="])
+    except getopt.GetoptError:
+        print (cmd)
+        sys.exit(2)
+    for opt, arg in opts:
+        if opt == '-h':
+            print (cmd)
+            sys.exit()
+        elif opt in ("-i", "--ifolder"):
+            markdownfolder = arg
+        elif opt in ("-o", "--ofolder"):
+            mkdocsfolder = arg
+
     yml_file = "mkdocs.yml"
     
     with open(yml_file, 'r') as yin:
         doc = yaml.load(yin, Loader=yaml.SafeLoader)
         for page in doc["nav"]:
             mk_file = list(page.values())[0]
-            source_file = md_template +"/"+ mk_file
+            source_file = markdownfolder +"/"+ mk_file
-            dest_file   = md_final +"/"+ mk_file
+            dest_file   = mkdocsfolder +"/"+ mk_file
             print("Processing %s -> %s" % (source_file, dest_file))
             with open(dest_file, 'w') as mdout:
                 with open(source_file, 'r') as mdin:

doc/manual/markdown2tex.py

@@ -54,7 +54,7 @@ def fix_tightlist(line):
         return line
 
 def main(argv):
-    docs_folder = "docs-template"
+    docs_folder = "docs"
     yml_file = "mkdocs.yml"
     mk_file  = "latex/btstack_generated.md"
 

doc/manual/mkdocs2html.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-import os, sys, shutil, re, pickle
+import os, sys, shutil, re, pickle, getopt
 from pathlib import Path
 
 def writeCodeBlock(aout, code, references):
@@ -12,15 +12,32 @@ def writeCodeBlock(aout, code, references):
 
 
 def main(argv):
-    html_path = "btstack/examples/"
+    htmlfolder = "btstack/"
-    html_tmppath = "btstack/examples/tmp/"
+    
+    cmd = 'mkdocs2html.py [-i <markdownfolder>] [-o <htmlkfolder>]'
+    
+    try:
+        opts, args = getopt.getopt(argv,"i:o:",["ifolder", "ofolder="])
+    except getopt.GetoptError:
+        print (cmd)
+        sys.exit(2)
+    for opt, arg in opts:
+        if opt == '-h':
+            print (cmd)
+            sys.exit()
+        elif opt in ("-o", "--ofolder"):
+            htmlfolder = arg
+        elif opt in ("-i", "--ifolder"):
+            markdownfolder = arg
+
+    html_path = htmlfolder + "examples/"
+    html_tmppath = htmlfolder + "examples/tmp/"
 
     html_in  = html_path + "examples/index.html"
     html_tmp = html_tmppath + "index.html"
-    references = pickle.load(open( "tmp/references.p", "rb" ))
+    references = pickle.load(open( markdownfolder + "references.p", "rb" ))
 
     Path(html_tmppath).mkdir(parents=True, exist_ok=True)
-
     
     codeblock = 0
     codeblock_end = 0

doc/manual/ports2markdown.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-import sys, os, shutil, re
+import sys, os, shutil, re,  getopt
 
 blacklist = []
 
@@ -77,13 +77,37 @@ def process_readmes(intro_file, port_folder, ports_file, ports_folder):
 
 def main(argv):
     btstackfolder = "../../"
-    docsfolder    = "docs-template/"
+    markdownfolder = "docs-markdown/"
-    template_folder = "template/"
+    templatefolder    = "docs-intro/"
     
+    cmd = 'ports2markdown.py [-r <root_btstackfolder>] [-t <templatefolder>] [-o <output_markdownfolder>]'
+    
+    try:
+        opts, args = getopt.getopt(argv,"r:t:o:",["rfolder=","tfolder=","ofolder="])
+    except getopt.GetoptError:
+        print (cmd)
+        sys.exit(2)
+    for opt, arg in opts:
+        if opt == '-h':
+            print (cmd)
+            sys.exit()
+        elif opt in ("-r", "--rfolder"):
+            btstackfolder = arg
+        elif opt in ("-t", "--tfolder"):
+            templatefolder = arg
+        elif opt in ("-o", "--ofolder"):
+            markdownfolder = arg
+
+
     inputfolder = btstackfolder   + "port/"
-    portsfolder = docsfolder      + "ports/"
+    portsfolder = markdownfolder      + "ports/"
-    introfile   = template_folder + "ports_intro.md"
+    introfile   = templatefolder + "ports_intro.md"
     outputfile  = portsfolder     + "existing_ports.md"
+
+    print ('Input folder: ', inputfolder)
+    print ('Intro file:   ', introfile)
+    print ('Output file:  ', outputfile)
+
     process_readmes(introfile, inputfolder, outputfile, portsfolder)
 
 if __name__ == "__main__":

doc/manual/update_apis.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 import os, sys, getopt, re, pickle
+import subprocess
 
 class State:
     SearchStartAPI = 0
@@ -90,9 +91,9 @@ api_ending = """
 code_ref = """GITHUBFPATH#LLINENR"""
 
 
-def codeReference(fname, githubfolder, filepath, linenr):
+def codeReference(fname, githuburl, filepath, linenr):
     global code_ref
-    ref = code_ref.replace("GITHUB", githubfolder)
+    ref = code_ref.replace("GITHUB", githuburl)
     ref = ref.replace("FPATH", filepath)
     ref = ref.replace("LINENR", str(linenr))
     return ref
@@ -127,7 +128,7 @@ def writeAPI(apifile, btstackfolder, apis, mk_codeidentation):
                         continue
 
 
-def createIndex(btstackfolder, apis, githubfolder):
+def createIndex(btstackfolder, apis, githuburl):
     global typedefs, functions
     
     for api_tuple in apis:
@@ -185,12 +186,12 @@ def createIndex(btstackfolder, apis, githubfolder):
                     typedef = re.match('}\s*(.*);\n', line)
                     if typedef:
                         typedefFound = 0
-                        typedefs[typedef.group(1)] = codeReference(typedef.group(1), githubfolder, api_tuple[0], linenr)
+                        typedefs[typedef.group(1)] = codeReference(typedef.group(1), githuburl, api_tuple[0], linenr)
                     continue
 
                 ref_function =  re.match('.*typedef\s+void\s+\(\s*\*\s*(.*?)\)\(.*', line)
                 if ref_function:
-                    functions[ref_function.group(1)] = codeReference(ref_function.group(1), githubfolder, api_tuple[0], linenr)
+                    functions[ref_function.group(1)] = codeReference(ref_function.group(1), githuburl, api_tuple[0], linenr)
                     continue
 
                 function = re.match('(.*?)\s*\(.*\(*.*;\n', line)
@@ -200,7 +201,7 @@ def createIndex(btstackfolder, apis, githubfolder):
                     if len(name) == 0:
                         print(parts);
                         sys.exit(10)
-                    functions[name] = codeReference( name, githubfolder, api_tuple[0], linenr)
+                    functions[name] = codeReference( name, githuburl, api_tuple[0], linenr)
                     continue
 
                 function = re.match('.(.*?)\s*\(.*\(*.*', line)
@@ -211,22 +212,19 @@ def createIndex(btstackfolder, apis, githubfolder):
                     parts = function.group(1).split(" ");
                     name = parts[len(parts)-1]
                     multiline_function_def = 1
-                    functions[name] = codeReference(name, githubfolder, api_tuple[0], linenr)
+                    functions[name] = codeReference(name, githuburl, api_tuple[0], linenr)
 
                         
 def main(argv):
     mk_codeidentation = "    "
-    
+    git_branch_name = "master"
     btstackfolder = "../../"
-    githubfolder  = "https://github.com/bluekitchen/btstack/blob/master/"
+    githuburl  = "https://github.com/bluekitchen/btstack/blob/master/"
+    markdownfolder = "docs-markdown/"
     
-    docsfolder    = "docs-template/"
+    cmd = 'update_apis.py [-r <root_btstackfolder>] [-g <githuburl>] [-o <output_markdownfolder>]'
-    apifile   = docsfolder + "appendix/apis.md"
-    indexfile = "api_index.md"
-
-    cmd = 'update_apis.py [-b <btstackfolder>] [-a <apifile>] [-g <githubfolder>] [-i <indexfile>]'
     try:
-        opts, args = getopt.getopt(argv,"hiso:",["bfolder=","afile=","gfolder=","ifile="])
+        opts, args = getopt.getopt(argv,"r:g:o:",["rfolder=","github=","ofolder="])
     except getopt.GetoptError:
         print (cmd)
         sys.exit(2)
@@ -234,21 +232,33 @@ def main(argv):
         if opt == '-h':
             print (cmd)
             sys.exit()
-        elif opt in ("-b", "--bfolder"):
+        elif opt in ("-r", "--rfolder"):
             btstackfolder = arg
-        elif opt in ("-a", "--afile"):
+        elif opt in ("-g", "--github"):
-            apifile = arg
+            githuburl = arg
-        elif opt in ("-g", "--gfolder"):
+        elif opt in ("-o", "--ofolder"):
-            btstackfolder = arg
+            markdownfolder = arg
-        elif opt in ("-i", "--ifile"):
+        
-            indexfile = arg
+    apifile   = markdownfolder + "appendix/apis.md"
+    indexfile = markdownfolder + "api_index.md"
+
+    try:
+        output = subprocess.check_output("git symbolic-ref --short HEAD", stderr=subprocess.STDOUT, timeout=3, shell=True)
+        git_branch_name = output.decode().rstrip()
+    except subprocess.CalledProcessError as exc:
+        print('GIT branch name: failed to get, use default value \"%s\""  ', git_branch_name, exc.returncode, exc.output)
+    else:
+        print ('GIT branch name :  %s' % git_branch_name)
+
+    githuburl = githuburl + git_branch_name
+
     print ('BTstack folder is : ' + btstackfolder)
     print ('API file is       : ' + apifile)
-    print ('Github path is    : ' + githubfolder)
+    print ('Github URL is    : ' +  githuburl)
     print ('Index file is     : ' + indexfile)
 
     writeAPI(apifile, btstackfolder, apis, mk_codeidentation)
-    createIndex(btstackfolder, apis, githubfolder)
+    createIndex(btstackfolder, apis, githuburl)
 
     for function in functions:
         parts = function.split(' ')
@@ -262,7 +272,7 @@ def main(argv):
         for function, reference in references.items():
             fout.write("[" + function + "](" + reference + ")\n")
             
-    pickle.dump(references, open( "tmp/references.p", "wb" ) )
+    pickle.dump(references, open( markdownfolder + "references.p", "wb" ) )
 
 if __name__ == "__main__":
    main(sys.argv[1:])

doc/manual/update_gatt_services.py

@@ -7,13 +7,6 @@ class State:
     IntroFound = 1
     SearchAPI = 2
 
-btstack_root    = os.path.abspath(os.path.dirname(sys.argv[0]) + '/../../')
-inputfolder     = btstack_root + "/src/ble/gatt-service/"
-
-manual_folder   = btstack_root + "/doc/manual/"
-docsfolder      = manual_folder + "docs-template/"
-template_folder = manual_folder + "template/"
-    
 mdfiles = {
     # source file sufix : docu file, [white list od source files]
     "_server.h" : ["gatt_services.md", ["hids_device.h"]],
@@ -121,12 +114,34 @@ def process_file(basename, inputfile_path, outputfile_path):
     fout.close()
     
 def main(argv):
+    btstackfolder   = os.path.abspath(os.path.dirname(sys.argv[0]) + '/../../')
+    inputfolder     = btstackfolder + "/src/ble/gatt-service/"
+    
+    markdownfolder = "docs-markdown/"
+    templatefolder    = "docs-intro/"
+    
+    cmd = 'update_gatt_services.py [-r <root_btstackfolder>] [-t <templatefolder>] [-o <output_markdownfolder>]'
+    
+    try:
+        opts, args = getopt.getopt(argv,"r:t:o:",["rfolder=","tfolder=","ofolder="])
+    except getopt.GetoptError:
+        print (cmd)
+        sys.exit(2)
+    for opt, arg in opts:
+        if opt == '-h':
+            print (cmd)
+            sys.exit()
+        elif opt in ("-r", "--rfolder"):
+            btstackfolder = arg
+        elif opt in ("-t", "--tfolder"):
+            templatefolder = arg
+        elif opt in ("-o", "--ofolder"):
+            markdownfolder = arg
+
+
     for source_filename_sufix, [outputfile, white_list] in mdfiles.items():
-        outputfile_path = docsfolder + outputfile 
+        outputfile_path = markdownfolder + outputfile 
-        introfile_path = template_folder + outputfile[:-3] + "_intro.md"
+        introfile_path = templatefolder + outputfile[:-3] + "_intro.md"
-        print('Code folder:  ', inputfolder)
-        print('Intro file:   ', introfile_path)
-        print('Output file:  ', outputfile_path)
         
         with open(outputfile_path, 'w') as fout:
             with open(introfile_path, 'r') as fin:

doc/manual/update_listings.py

@@ -340,17 +340,12 @@ def processExamples(intro_file, examples_folder, examples_ofile, git_branch_name
 
 def main(argv):
     btstackfolder = "../../"
-    docsfolder    = "docs-template/"
-    template_folder = "template/"
     git_branch_name = "master"
 
-    inputfolder = btstackfolder + "example/"
+    cmd = 'update_listings.py [-r <root_btstackfolder>] [-t <templatefolder>] [-o <output_markdownfolder>]'
-    introfile   = template_folder + "examples_intro.md"
-    outputfile  = docsfolder + "examples/examples.md"
     
-    cmd = 'update_listings.py [-f <inputfolder>] [-i <introfile>] [-o <outputfile>]'
     try:
-        opts, args = getopt.getopt(argv,"hiso:",["ffolder=","ifile=","ofile="])
+        opts, args = getopt.getopt(argv,"r:t:o:",["rfolder=","tfolder=","ofolder="])
     except getopt.GetoptError:
         print (cmd)
         sys.exit(2)
@@ -358,14 +353,20 @@ def main(argv):
         if opt == '-h':
             print (cmd)
             sys.exit()
-        elif opt in ("-f", "--ffolder"):
+        elif opt in ("-r", "--rfolder"):
-            inputfolder = arg
+            btstackfolder = arg
-        elif opt in ("-i", "--ifile"):
+        elif opt in ("-t", "--tfolder"):
-            introfile = arg
+            templatefolder = arg
-        elif opt in ("-o", "--ofile"):
+        elif opt in ("-o", "--ofolder"):
-            outputfile = arg
+            markdownfolder = arg
-    print ('Input folder: ', inputfolder)
+
-    print ('Intro file:   ', introfile)
+
+    examples_folder    = btstackfolder + "example/"
+    examples_introfile = templatefolder + "examples_intro.md"
+    outputfile         = markdownfolder + "examples/examples.md"
+
+    print ('Input folder: ', examples_folder)
+    print ('Intro file:   ', examples_introfile)
     print ('Output file:  ', outputfile)
     
     try:
@@ -376,7 +377,7 @@ def main(argv):
     else:
         print ('GIT branch name :  %s' % git_branch_name)
     
-    processExamples(introfile, inputfolder, outputfile, git_branch_name)
+    processExamples(examples_introfile, examples_folder, outputfile, git_branch_name)
 
 if __name__ == "__main__":
    main(sys.argv[1:])