diff --git a/chipset/README.md b/chipset/README.md index 7eade0347..56e2dff90 100644 --- a/chipset/README.md +++ b/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. diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 96fc15ffa..b9f34a2cd 100644 --- a/doc/manual/Makefile +++ b/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: - # docs -> docs_final - ./markdown2mkdocs.py - # generate HTML +all: html pdf + +docs-markdown: + # 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-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 docs-markdown docs tmp btstack *.pdf latex/btstack_generated.* latex/btstack_final.tex mkdocs.yml rm -rf latex btstack help diff --git a/doc/manual/template/examples_intro.md b/doc/manual/docs-intro/examples_intro.md similarity index 100% rename from doc/manual/template/examples_intro.md rename to doc/manual/docs-intro/examples_intro.md diff --git a/doc/manual/template/gatt_clients_intro.md b/doc/manual/docs-intro/gatt_clients_intro.md similarity index 100% rename from doc/manual/template/gatt_clients_intro.md rename to doc/manual/docs-intro/gatt_clients_intro.md diff --git a/doc/manual/template/gatt_services_intro.md b/doc/manual/docs-intro/gatt_services_intro.md similarity index 100% rename from doc/manual/template/gatt_services_intro.md rename to doc/manual/docs-intro/gatt_services_intro.md diff --git a/doc/manual/template/ports_intro.md b/doc/manual/docs-intro/ports_intro.md similarity index 100% rename from doc/manual/template/ports_intro.md rename to doc/manual/docs-intro/ports_intro.md diff --git a/doc/manual/docs-template/docs/appendix/events_errors.md b/doc/manual/docs-template/appendix/events_errors.md similarity index 100% rename from doc/manual/docs-template/docs/appendix/events_errors.md rename to doc/manual/docs-template/appendix/events_errors.md diff --git a/doc/manual/docs-template/docs/appendix/migration.md b/doc/manual/docs-template/appendix/migration.md similarity index 100% rename from doc/manual/docs-template/docs/appendix/migration.md rename to doc/manual/docs-template/appendix/migration.md diff --git a/doc/manual/docs-template/docs/architecture.md b/doc/manual/docs-template/architecture.md similarity index 100% rename from doc/manual/docs-template/docs/architecture.md rename to doc/manual/docs-template/architecture.md diff --git a/doc/manual/docs-template/docs/.gitignore b/doc/manual/docs-template/docs/.gitignore deleted file mode 100644 index 8a125d638..000000000 --- a/doc/manual/docs-template/docs/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -gatt_clients.md -gatt_services.md \ No newline at end of file diff --git a/doc/manual/docs-template/docs/appendix/.gitignore b/doc/manual/docs-template/docs/appendix/.gitignore deleted file mode 100644 index 138676bc2..000000000 --- a/doc/manual/docs-template/docs/appendix/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -apis.md -index.md diff --git a/doc/manual/docs-template/docs/btstack.css b/doc/manual/docs-template/docs/btstack.css deleted file mode 100644 index 7e80280a3..000000000 --- a/doc/manual/docs-template/docs/btstack.css +++ /dev/null @@ -1,2 +0,0 @@ -a.toctree-l3 { display: none; } -a.toctree-l4 { display: none; } diff --git a/doc/manual/docs-template/docs/examples/.gitignore b/doc/manual/docs-template/docs/examples/.gitignore deleted file mode 100644 index 9f3dc4d59..000000000 --- a/doc/manual/docs-template/docs/examples/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -examples.md -generated.md diff --git a/doc/manual/docs-template/docs/ports/.gitignore b/doc/manual/docs-template/docs/ports/.gitignore deleted file mode 100644 index 4d6a648cf..000000000 --- a/doc/manual/docs-template/docs/ports/.gitignore +++ /dev/null @@ -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 diff --git a/doc/manual/docs-template/docs/how_to.md b/doc/manual/docs-template/how_to.md similarity index 100% rename from doc/manual/docs-template/docs/how_to.md rename to doc/manual/docs-template/how_to.md diff --git a/doc/manual/docs-template/docs/index.md b/doc/manual/docs-template/index.md similarity index 100% rename from doc/manual/docs-template/docs/index.md rename to doc/manual/docs-template/index.md diff --git a/doc/manual/docs-template/docs/integration.md b/doc/manual/docs-template/integration.md similarity index 100% rename from doc/manual/docs-template/docs/integration.md rename to doc/manual/docs-template/integration.md diff --git a/doc/manual/docs-template/docs/picts/bklogo.pdf b/doc/manual/docs-template/picts/bklogo.pdf similarity index 100% rename from doc/manual/docs-template/docs/picts/bklogo.pdf rename to doc/manual/docs-template/picts/bklogo.pdf diff --git a/doc/manual/docs-template/docs/picts/bklogo.png b/doc/manual/docs-template/picts/bklogo.png similarity index 100% rename from doc/manual/docs-template/docs/picts/bklogo.png rename to doc/manual/docs-template/picts/bklogo.png diff --git a/doc/manual/docs-template/docs/picts/btstack-architecture.pdf b/doc/manual/docs-template/picts/btstack-architecture.pdf similarity index 100% rename from doc/manual/docs-template/docs/picts/btstack-architecture.pdf rename to doc/manual/docs-template/picts/btstack-architecture.pdf diff --git a/doc/manual/docs-template/docs/picts/btstack-architecture.png b/doc/manual/docs-template/picts/btstack-architecture.png similarity index 100% rename from doc/manual/docs-template/docs/picts/btstack-architecture.png rename to doc/manual/docs-template/picts/btstack-architecture.png diff --git a/doc/manual/docs-template/docs/picts/btstack-figs.pptx b/doc/manual/docs-template/picts/btstack-figs.pptx similarity index 100% rename from doc/manual/docs-template/docs/picts/btstack-figs.pptx rename to doc/manual/docs-template/picts/btstack-figs.pptx diff --git a/doc/manual/docs-template/docs/picts/btstack-protocols.pdf b/doc/manual/docs-template/picts/btstack-protocols.pdf similarity index 100% rename from doc/manual/docs-template/docs/picts/btstack-protocols.pdf rename to doc/manual/docs-template/picts/btstack-protocols.pdf diff --git a/doc/manual/docs-template/docs/picts/btstack-protocols.png b/doc/manual/docs-template/picts/btstack-protocols.png similarity index 100% rename from doc/manual/docs-template/docs/picts/btstack-protocols.png rename to doc/manual/docs-template/picts/btstack-protocols.png diff --git a/doc/manual/docs-template/docs/picts/gatt_client_security.txt b/doc/manual/docs-template/picts/gatt_client_security.txt similarity index 100% rename from doc/manual/docs-template/docs/picts/gatt_client_security.txt rename to doc/manual/docs-template/picts/gatt_client_security.txt diff --git a/doc/manual/docs-template/docs/picts/gatt_client_security_mandatory_authentication_central.svg b/doc/manual/docs-template/picts/gatt_client_security_mandatory_authentication_central.svg similarity index 100% rename from doc/manual/docs-template/docs/picts/gatt_client_security_mandatory_authentication_central.svg rename to doc/manual/docs-template/picts/gatt_client_security_mandatory_authentication_central.svg diff --git a/doc/manual/docs-template/docs/picts/gatt_client_security_mandatory_authentication_peripheral.svg b/doc/manual/docs-template/picts/gatt_client_security_mandatory_authentication_peripheral.svg similarity index 100% rename from doc/manual/docs-template/docs/picts/gatt_client_security_mandatory_authentication_peripheral.svg rename to doc/manual/docs-template/picts/gatt_client_security_mandatory_authentication_peripheral.svg diff --git a/doc/manual/docs-template/docs/picts/gatt_client_security_proactive_authentication_central.svg b/doc/manual/docs-template/picts/gatt_client_security_proactive_authentication_central.svg similarity index 100% rename from doc/manual/docs-template/docs/picts/gatt_client_security_proactive_authentication_central.svg rename to doc/manual/docs-template/picts/gatt_client_security_proactive_authentication_central.svg diff --git a/doc/manual/docs-template/docs/picts/gatt_client_security_proactive_authentication_peripheral.svg b/doc/manual/docs-template/picts/gatt_client_security_proactive_authentication_peripheral.svg similarity index 100% rename from doc/manual/docs-template/docs/picts/gatt_client_security_proactive_authentication_peripheral.svg rename to doc/manual/docs-template/picts/gatt_client_security_proactive_authentication_peripheral.svg diff --git a/doc/manual/docs-template/docs/picts/gatt_client_security_reactive_authentication_central.svg b/doc/manual/docs-template/picts/gatt_client_security_reactive_authentication_central.svg similarity index 100% rename from doc/manual/docs-template/docs/picts/gatt_client_security_reactive_authentication_central.svg rename to doc/manual/docs-template/picts/gatt_client_security_reactive_authentication_central.svg diff --git a/doc/manual/docs-template/docs/picts/gatt_client_security_reactive_authentication_peripheral.svg b/doc/manual/docs-template/picts/gatt_client_security_reactive_authentication_peripheral.svg similarity index 100% rename from doc/manual/docs-template/docs/picts/gatt_client_security_reactive_authentication_peripheral.svg rename to doc/manual/docs-template/picts/gatt_client_security_reactive_authentication_peripheral.svg diff --git a/doc/manual/docs-template/docs/picts/host_chipset_connection.pdf b/doc/manual/docs-template/picts/host_chipset_connection.pdf similarity index 100% rename from doc/manual/docs-template/docs/picts/host_chipset_connection.pdf rename to doc/manual/docs-template/picts/host_chipset_connection.pdf diff --git a/doc/manual/docs-template/docs/picts/host_chipset_connection.png b/doc/manual/docs-template/picts/host_chipset_connection.png similarity index 100% rename from doc/manual/docs-template/docs/picts/host_chipset_connection.png rename to doc/manual/docs-template/picts/host_chipset_connection.png diff --git a/doc/manual/docs-template/docs/picts/multithreading-btdaemon.pdf b/doc/manual/docs-template/picts/multithreading-btdaemon.pdf similarity index 100% rename from doc/manual/docs-template/docs/picts/multithreading-btdaemon.pdf rename to doc/manual/docs-template/picts/multithreading-btdaemon.pdf diff --git a/doc/manual/docs-template/docs/picts/multithreading-btdaemon.png b/doc/manual/docs-template/picts/multithreading-btdaemon.png similarity index 100% rename from doc/manual/docs-template/docs/picts/multithreading-btdaemon.png rename to doc/manual/docs-template/picts/multithreading-btdaemon.png diff --git a/doc/manual/docs-template/docs/picts/multithreading-monolithic.pdf b/doc/manual/docs-template/picts/multithreading-monolithic.pdf similarity index 100% rename from doc/manual/docs-template/docs/picts/multithreading-monolithic.pdf rename to doc/manual/docs-template/picts/multithreading-monolithic.pdf diff --git a/doc/manual/docs-template/docs/picts/multithreading-monolithic.png b/doc/manual/docs-template/picts/multithreading-monolithic.png similarity index 100% rename from doc/manual/docs-template/docs/picts/multithreading-monolithic.png rename to doc/manual/docs-template/picts/multithreading-monolithic.png diff --git a/doc/manual/docs-template/docs/picts/singlethreading-btstack.pdf b/doc/manual/docs-template/picts/singlethreading-btstack.pdf similarity index 100% rename from doc/manual/docs-template/docs/picts/singlethreading-btstack.pdf rename to doc/manual/docs-template/picts/singlethreading-btstack.pdf diff --git a/doc/manual/docs-template/docs/picts/singlethreading-btstack.png b/doc/manual/docs-template/picts/singlethreading-btstack.png similarity index 100% rename from doc/manual/docs-template/docs/picts/singlethreading-btstack.png rename to doc/manual/docs-template/picts/singlethreading-btstack.png diff --git a/doc/manual/docs-template/docs/porting.md b/doc/manual/docs-template/porting.md similarity index 100% rename from doc/manual/docs-template/docs/porting.md rename to doc/manual/docs-template/porting.md diff --git a/doc/manual/docs-template/docs/profiles.md b/doc/manual/docs-template/profiles.md similarity index 100% rename from doc/manual/docs-template/docs/profiles.md rename to doc/manual/docs-template/profiles.md diff --git a/doc/manual/docs-template/docs/protocols.md b/doc/manual/docs-template/protocols.md similarity index 100% rename from doc/manual/docs-template/docs/protocols.md rename to doc/manual/docs-template/protocols.md diff --git a/doc/manual/docs-template/docs/quick_start.md b/doc/manual/docs-template/quick_start.md similarity index 100% rename from doc/manual/docs-template/docs/quick_start.md rename to doc/manual/docs-template/quick_start.md diff --git a/doc/manual/markdown2mkdocs.py b/doc/manual/markdown2mkdocs.py index ca7ee4072..93813ec98 100755 --- a/doc/manual/markdown2mkdocs.py +++ b/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" - md_final = "docs" + markdownfolder = "docs-markdown/" + mkdocsfolder = "docs/" + + cmd = 'markdown2mkdocs.py [-i ] [-o ] ' + + 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 - dest_file = md_final +"/"+ mk_file + source_file = markdownfolder +"/"+ 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: diff --git a/doc/manual/markdown2tex.py b/doc/manual/markdown2tex.py index a244316df..cac98b534 100755 --- a/doc/manual/markdown2tex.py +++ b/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" diff --git a/doc/manual/mkdocs2html.py b/doc/manual/mkdocs2html.py index 4a8bbc4fe..12c87a4fa 100755 --- a/doc/manual/mkdocs2html.py +++ b/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/" - html_tmppath = "btstack/examples/tmp/" + htmlfolder = "btstack/" + + cmd = 'mkdocs2html.py [-i ] [-o ]' + + 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 diff --git a/doc/manual/ports2markdown.py b/doc/manual/ports2markdown.py index e0a351e74..0e80de503 100755 --- a/doc/manual/ports2markdown.py +++ b/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/" - template_folder = "template/" + markdownfolder = "docs-markdown/" + templatefolder = "docs-intro/" + cmd = 'ports2markdown.py [-r ] [-t ] [-o ]' + + 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/" - introfile = template_folder + "ports_intro.md" + portsfolder = markdownfolder + "ports/" + 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__": diff --git a/doc/manual/update_apis.py b/doc/manual/update_apis.py index f6294c5e8..5a01fd00b 100755 --- a/doc/manual/update_apis.py +++ b/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/" - apifile = docsfolder + "appendix/apis.md" - indexfile = "api_index.md" - - cmd = 'update_apis.py [-b ] [-a ] [-g ] [-i ]' + cmd = 'update_apis.py [-r ] [-g ] [-o ]' 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"): - apifile = arg - elif opt in ("-g", "--gfolder"): - btstackfolder = arg - elif opt in ("-i", "--ifile"): - indexfile = arg + elif opt in ("-g", "--github"): + githuburl = arg + elif opt in ("-o", "--ofolder"): + markdownfolder = 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:]) diff --git a/doc/manual/update_gatt_services.py b/doc/manual/update_gatt_services.py index de257498f..cb20fffae 100755 --- a/doc/manual/update_gatt_services.py +++ b/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 ] [-t ] [-o ]' + + 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 - introfile_path = template_folder + outputfile[:-3] + "_intro.md" - print('Code folder: ', inputfolder) - print('Intro file: ', introfile_path) - print('Output file: ', outputfile_path) + outputfile_path = markdownfolder + outputfile + introfile_path = templatefolder + outputfile[:-3] + "_intro.md" with open(outputfile_path, 'w') as fout: with open(introfile_path, 'r') as fin: diff --git a/doc/manual/update_listings.py b/doc/manual/update_listings.py index 2cd95515d..6641a47bf 100755 --- a/doc/manual/update_listings.py +++ b/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/" - introfile = template_folder + "examples_intro.md" - outputfile = docsfolder + "examples/examples.md" + cmd = 'update_listings.py [-r ] [-t ] [-o ]' - cmd = 'update_listings.py [-f ] [-i ] [-o ]' 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"): - inputfolder = arg - elif opt in ("-i", "--ifile"): - introfile = arg - elif opt in ("-o", "--ofile"): - outputfile = arg - print ('Input folder: ', inputfolder) - print ('Intro file: ', introfile) + elif opt in ("-r", "--rfolder"): + btstackfolder = arg + elif opt in ("-t", "--tfolder"): + templatefolder = arg + elif opt in ("-o", "--ofolder"): + markdownfolder = arg + + + 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:])