mirror/btstack
1
0
Fork 0
mirror of https://github.com/bluekitchen/btstack.git synced 2025-01-29 12:32:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: update pdf generation

Browse Source
This commit is contained in:
Milanka Ringwald 2021-05-28 15:35:09 +02:00
parent 90f75057f9
commit 78fab72ea4
6 changed files with 123 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/manual/.gitignore vendored
View File

@ -3,6 +3,7 @@ btstack.pdf
docs
docs-markdown
latex
mkdocs-latex.yml
mkdocs-temp.yml
mkdocs.yml
references.p

44
doc/manual/Makefile
View File

@ -4,15 +4,16 @@ INTRO_FOLDER = docs-intro/
MARKDOWN_FOLDER = docs-markdown/
MKDOCS_FOLDER = docs/
HTML_FOLDER = btstack/
LATEX_FOLDER = latex/
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
rm -rf ${MARKDOWN_FOLDER}
cp -r docs-template ${MARKDOWN_FOLDER}
mkdir ${MARKDOWN_FOLDER}/examples
mkdir ${MARKDOWN_FOLDER}/ports
# create mkdocs-temp.yml
./update_mkdocs_yml.sh
@ -20,12 +21,12 @@ docs-markdown:
# 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
sed -e "s|../doc/manual/docs-template/||g" ../../chipset/README.md > ${MARKDOWN_FOLDER}/chipsets.md
# create docs-markdown/appendix/apis.md
# create docs-markdown/api_index.md
# create references.p
# create mkdocs.yml
# create mkdocs-latex.yml
./markdown_create_apis.py -r ${BTSTACK_FOLDER} -g ${GITHUB_URL} -o ${MARKDOWN_FOLDER}
# create docs-markdown/examples/examples.md
@ -39,8 +40,8 @@ docs-markdown:
docs: docs-markdown
# create new docs
rm -rf docs
cp -r docs-markdown docs
rm -rf ${MKDOCS_FOLDER}
cp -r ${MARKDOWN_FOLDER} ${MKDOCS_FOLDER}
# docs-markdown -> docs
./markdown_update_references.py -i ${MARKDOWN_FOLDER} -o ${MKDOCS_FOLDER}
@ -54,16 +55,20 @@ html: docs
./html_postprocess_code_blocks.py -o ${HTML_FOLDER}
pdf: docs
rm -rf latex
mkdir -p latex
cp -r docs/picts latex
rm -rf ${LATEX_FOLDER}
mkdir -p ${LATEX_FOLDER}
cp -r ${MKDOCS_FOLDER}/picts ${LATEX_FOLDER}
cp mkdocs-latex.yml mkdocs.yml
# create latex/btstack_gettingstartec.tex with version
./update_getting_started.sh
./update_getting_started.sh ${LATEX_FOLDER}
# create latex/btstack_generated.md -> latex/btstack_final.tex
./markdown2tex.py
cp docs/ports/*.jpg latex
cd latex && pdflatex btstack_gettingstarted.tex && pdflatex btstack_gettingstarted.tex
mv latex/btstack_gettingstarted.pdf btstack.pdf
./markdown2tex.py -i ${MKDOCS_FOLDER} -o ${LATEX_FOLDER}
cp ${MKDOCS_FOLDER}/ports/*.jpg ${LATEX_FOLDER}
cd ${LATEX_FOLDER} && pdflatex btstack_gettingstarted.tex && pdflatex btstack_gettingstarted.tex
mv ${LATEX_FOLDER}/btstack_gettingstarted.pdf btstack.pdf
preview: docs
# race condition, open browser before starting MKdocs server
@ -71,8 +76,9 @@ preview: docs
mkdocs serve -a localhost:8010
clean:
rm -rf docs-markdown docs tmp btstack *.pdf latex/btstack_generated.* latex/btstack_final.tex mkdocs.yml
rm -rf latex btstack help
rm -rf references.p mkdocs-temp.yml
rm -rf ${MARKDOWN_FOLDER} ${LATEX_FOLDER} ${HTML_FOLDER} ${MKDOCS_FOLDER}
rm -f *.pdf
rm -f references.p
rm -f mkdocs.yml mkdocs-latex.yml mkdocs-temp.yml

77
doc/manual/markdown2tex.py
View File

@ -1,7 +1,12 @@
#!/usr/bin/env python3
import sys, yaml
import os, re
import os, re, getopt
pandoc_cmd_template = """
pandoc -f markdown -t latex --filter pandoc-fignos --filter pandoc-tablenos --listings LATEX_FOLDERbtstack_generated.md -o LATEX_FOLDERbtstack_generated.tex
"""
figures = {
'btstack-architecture' : '1',
@ -53,32 +58,54 @@ def fix_tightlist(line):
else:
return line
def main(argv):
docs_folder = "docs"
yml_file = "mkdocs.yml"
mk_file = "latex/btstack_generated.md"
def postprocess_file(markdown_filepath, fout, title):
with open(markdown_filepath, 'r') as fin:
for line in fin:
if line == "#\n":
fout.write("\n\n#"+ title +"\n\n")
continue
# remove path from section reference
# e.g. [the SPP Counter example](examples/generated/#sec:sppcounterExample)
# replace with [the SPP Counter example](#sec:sppcounterExample)
section_ref = re.match('.*\(((.*)(#sec:.*))\).*',line)
if section_ref:
line = line.replace(section_ref.group(2),"")
fout.write(line)
with open(mk_file, 'w') as aout:
with open(yml_file, 'r') as yin:
def main(argv):
yml_file = "mkdocs.yml"
latexfolder = "latex/"
mkdocsfolder = "docs/"
cmd = 'markdown2tex.py [-i <mkdocsfolder>] [-o <latexfolder>] '
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"):
mkdocsfolder = arg
elif opt in ("-o", "--ofolder"):
latexfolder = arg
latex_filepath = latexfolder + "btstack_generated.md"
with open(latex_filepath, 'wt') as fout:
with open(yml_file, 'rt') as yin:
doc = yaml.load(yin, Loader=yaml.SafeLoader)
for page in doc["nav"]:
title = list(page.keys())[0]
md_file = list(page.values())[0]
with open(docs_folder +"/"+ md_file, 'r') as mdin:
for line in mdin:
if line == "#\n":
aout.write("\n\n#"+ title +"\n\n")
continue
# remove path from section reference
# e.g. [the SPP Counter example](examples/generated/#sec:sppcounterExample)
# replace with [the SPP Counter example](#sec:sppcounterExample)
section_ref = re.match('.*\(((.*)(#sec:.*))\).*',line)
if section_ref:
line = line.replace(section_ref.group(2),"")
aout.write(line)
navigation_group_filepath = list(page.values())[0]
navigation_group_title = list(page.keys())[0]
markdown_filepath = mkdocsfolder + navigation_group_filepath
postprocess_file(markdown_filepath, fout, navigation_group_title)
pandoc_cmd = pandoc_cmd_template.replace("LATEX_FOLDER", latexfolder)
pandoc_cmd = "pandoc -f markdown -t latex --filter pandoc-fignos --filter pandoc-tablenos --listings latex/btstack_generated.md -o latex/btstack_generated.tex"
p = os.popen(pandoc_cmd,"r")
while 1:
line = p.readline()
@ -87,8 +114,8 @@ def main(argv):
# btstatck_root_file = "latex/btstack_gettingstarted.tex"
btstack_generated_file = "latex/btstack_generated.tex"
btstack_final_file = "latex/btstack_final.tex"
btstack_generated_file = latexfolder + "btstack_generated.tex"
btstack_final_file = latexfolder + "btstack_final.tex"
with open(btstack_final_file, 'w') as aout:
aout.write("% !TEX root = btstack_gettingstarted.tex\n\n")

35
doc/manual/markdown_create_apis.py
View File

@ -23,6 +23,10 @@ state = State.SearchStartAPI
api_header = """
# API_TITLE API {#sec:API_LABEL_api}
"""
api_subheader = """
## API_TITLE API {#sec:API_LABEL_api}
"""
api_ending = """
@ -286,11 +290,32 @@ def main(argv):
markdown_reference = "appendix/" + filename_stem(header_filepath) + ".md"
fout.write(identation + "'" + header_title + "': " + markdown_reference + "\n")
for function in functions:
parts = function.split(' ')
if (len(parts) > 1):
print (parts)
# create singe appendix/apis.md for latex
with open("mkdocs-temp.yml", 'rt') as fin:
with open("mkdocs-latex.yml", 'wt') as fout:
for line in fin:
if not isTagAPI(line):
fout.write(line)
continue
fout.write(" - 'APIs': appendix/apis.md\n")
markdown_filepath = markdownfolder + "appendix/apis.md"
with open(markdown_filepath, 'wt') as fout:
fout.write("\n# APIs\n\n")
for header_filepath in sorted(header_files.keys()):
header_label = filename_stem(header_filepath) # file name without
header_description = header_files[header_filepath][1]
subheader_title = api_subheader.replace("API_TITLE", header_files[header_filepath][0]).replace("API_LABEL", header_label)
with open(header_filepath, 'rt') as fin:
fout.write(subheader_title)
fout.write(header_description)
writeAPI(fout, fin, mk_codeidentation)
references = functions.copy()
references.update(typedefs)

24
doc/manual/markdown_update_references.py
View File

@ -121,20 +121,24 @@ def main(argv):
with open(yml_file, 'r') as yin:
doc = yaml.load(yin, Loader=yaml.SafeLoader)
# page is either:
# - {title: filepath} dictionary for a direcr yml reference (e.g. - 'Welcome': index.md), or
# - {navigation_group_title: [{title: filepath}, ...] } dictionary for a navigation group
for page in doc["nav"]:
# navigation item is either:
# - a string for a simple reference, (e.g. - 'Welcome': index.md), or
# - a list of dictionaries for a navigation group [{file_path : title}]
navigation_item = list(page.values())[0]
# navigation_group_filepath is either:
# - filepath string for a direcr yml reference (e.g. - 'Welcome': index.md), or
# - list of [{title: filepath}, ...] dictionaries for each item in navigation group
navigation_group_filepath = list(page.values())[0]
if type(navigation_item) == str:
process_file(navigation_item, markdownfolder, mkdocsfolder)
if type(navigation_group_filepath) == str:
process_file(navigation_group_filepath, markdownfolder, mkdocsfolder)
continue
if type(navigation_item) == list:
for file_description_dict in navigation_item:
api_filepath = list(file_description_dict.values())[0]
process_file(api_filepath, markdownfolder, mkdocsfolder)
if type(navigation_group_filepath) == list:
for file_description_dict in navigation_group_filepath:
filepath = list(file_description_dict.values())[0]
process_file(filepath, markdownfolder, mkdocsfolder)
continue

2
doc/manual/update_getting_started.sh
View File

@ -14,4 +14,4 @@ else
fi
# create mkdocs.yml
sed -e "s|VERSION|$version|" btstack_gettingstarted.tex > latex/btstack_gettingstarted.tex
sed -e "s|VERSION|$version|" btstack_gettingstarted.tex > $1/btstack_gettingstarted.tex