From: Sebastien Douheret Date: Mon, 19 Jun 2017 13:48:58 +0000 (+0200) Subject: Add gitbook documentation (support PDF generation). X-Git-Tag: dab/3.99.2~16 X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?p=src%2Fapp-framework-main.git;a=commitdiff_plain;h=7e984551f7ca2e883c5a58cd8dae71dba0db6240 Add gitbook documentation (support PDF generation). To generate PDF doc: ./gendocs.sh pdf To generate HTML doc (local webserver): ./gendocs.sh serve Change-Id: Ib9b195814f4596a5cf5233d6a331d206e76c9bae Signed-off-by: Sebastien Douheret --- diff --git a/.gitignore b/.gitignore index 9964491..6357f3f 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,5 @@ build/ tests-w3c/ prepare-build.sh +node_modules/ +_book/ \ No newline at end of file diff --git a/book.json b/book.json new file mode 100644 index 0000000..da8c185 --- /dev/null +++ b/book.json @@ -0,0 +1,93 @@ +{ + "title": "Application Framework Service", + "description": "Application Framework Service of Automotive Grade Linux", + "keywords": "AGL, Development, application, framework, service", + "author": "IoT.Bzh Team", + "website": "http://iot.bzh", + "published": "June 2017", + "version": "4.0", + + "gitbook": "3.2.2", + "root": "docs", + "pdf": { + "fontFamily": "Verdana", + "fontSize": 12, + "paperSize": "a4", + "pageBreaksBefore": "//h:div[@class=\"page-break\"]" + }, + "styles": { + "website": "resources/ebook.css", + "ebook": "resources/ebook.css", + "pdf": "resources/ebook.css" + }, + + "hidepageheaders": [2], + "hidepagefooters": [2], + + "plugins": [ + "regexplace" + ], + "pluginsConfig": { + "regexplace": { + "removeFirstPartsInSectionNumber": true, + "substitutes": [{ + "pattern": "", + "flags": "g", + "substitute": "

" + }, + { + "pattern": "", + "flags": "g", + "substitute": "

" + }, + { + "pattern": "!\\[(.*?)\\]\$(.*?)(?:\\s+\"(.*)\")?\${0,}{caption=1([^\\}]*)}", + "flags": "gmi", + "substitute": "

", + "decode": true + }, + { + "pattern": "]*) {0,}\/{0,}> {0,}{caption=1([^\\}]*)}", + "flags": "g", + "substitute": "

", + "decode": true + }, + { + "pattern": "

", + "flags": "g", + "substitute": "

Picture _PAGE_LEVEL_._INDEX_: $2

", + "store": { + "substitute": "Pic. _PAGE_LEVEL_._INDEX_ $2", + "variable_name": "pictures" + } + }, + { + "pattern": "]*)> {0,}{style {1,}([^}]*)}", + "flags": "g", + "substitute": "", + "decode": true + } + ] + } + } +} diff --git a/docs/1-frameworks.md b/docs/1-frameworks.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/2-widgets.md b/docs/2-widgets.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/overview.md b/docs/README.md similarity index 99% rename from docs/overview.md rename to docs/README.md index f0441da..3373968 100644 --- a/docs/overview.md +++ b/docs/README.md @@ -79,7 +79,7 @@ This documentation explains the framework created by IoT.bzh by rewriting the Tizen Application Framework. Be aware of the previous foreword. - + Overview -------- @@ -87,7 +87,7 @@ The figure below shows the major components of the framework and their interactions going through the following scenario: APPLICATION installs an other application and then launch it. -![AppFW-APP_install_sequences][AppFW-APP_install_sequences] +![AppFW-APP_install_sequences][AppFW-APP_install_sequences]{style width:70%} Let follow the sequence of calls: diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..7357214 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,11 @@ +# Summary + +* [Overview](README.md) +* [Quick tutorial](quick-tutorial.md) +* [The frameworks](1-frameworks.md) + * [The application framework](application-framework.md) + * [The security framework](security-framework.md) +* [The afm daemons](afm-daemons.md) +* [Widgets of the framework](2-widgets.md) + * [Overview of widgets](widgets.md) + * [The configuration file](config.xml.md) \ No newline at end of file diff --git a/docs/_layouts/ebook/page.html b/docs/_layouts/ebook/page.html new file mode 100644 index 0000000..bf325e9 --- /dev/null +++ b/docs/_layouts/ebook/page.html @@ -0,0 +1,36 @@ +{% extends "layout.html" %} + +{% block title %}{{ page.title }}{% endblock %} +{% block description %}{{ page.description }}{% endblock %} + +{% block style %} + {### Include theme css before plugins css ###} + {% if not fileExists(config.styles.print) %} + {% if options.format %} + + {% else %} + + {% endif %} + {% endif %} + + {{ super() }} + + {### Custom stylesheets for the book ###} + + {% for type, style in config.styles %} + {% if fileExists(style) and (type == "ebook" or type == "print" or type == options.format) %} + + {% endif %} + {% endfor %} +{% endblock %} + +{% block body %} +

+ {% block page %} +

+ {{ page.content|safe }} +

+ {% endblock %} +

+{% endblock %} diff --git a/docs/_layouts/ebook/pdf_footer.html b/docs/_layouts/ebook/pdf_footer.html new file mode 100644 index 0000000..679e562 --- /dev/null +++ b/docs/_layouts/ebook/pdf_footer.html @@ -0,0 +1,13 @@ +{% extends "./page.html" %} +{% block body %} + + + + +{% endblock %} diff --git a/docs/_layouts/ebook/pdf_header.html b/docs/_layouts/ebook/pdf_header.html new file mode 100644 index 0000000..ef49641 --- /dev/null +++ b/docs/_layouts/ebook/pdf_header.html @@ -0,0 +1,13 @@ +{% extends "./page.html" %} +{% block body %} +

+ IoT.Bzh + {{ config.title }} +

+ + + + +{% endblock %} \ No newline at end of file diff --git a/docs/_layouts/ebook/summary.html b/docs/_layouts/ebook/summary.html new file mode 100644 index 0000000..be328a4 --- /dev/null +++ b/docs/_layouts/ebook/summary.html @@ -0,0 +1,58 @@ +{% extends "./page.html" %} + +{% block title %}{{ "SUMMARY"|t }}{% endblock %} + +{% macro articles(_articles) %} + {% for article in _articles %} +

+ + {% if article.path or article.url %} + {% if article.path %} + {{ article.title }} + {% else %} + {{ article.title }} + {% endif %} + {% else %} + {{ article.title }} + {% endif %} + {% if 1 %} + {{ article.level }} + {% endif %} + + {% if article.articles.length > 0 %} +

+ {{ articles(article.articles) }} + + {% endif %} +

+ {% endfor %} +{% endmacro %} + +{% block page %} +

+
{{ part.title }}
+
+ + {{ "GLOSSARY"|t }} + +

+{% endblock %} + diff --git a/docs/_layouts/layout.html b/docs/_layouts/layout.html new file mode 100644 index 0000000..3d5aca6 --- /dev/null +++ b/docs/_layouts/layout.html @@ -0,0 +1,28 @@ + + + + + + {% block title %}{{ config.title|d("GitBook", true) }}{% endblock %} + + + + {% if config.author %}{% endif %} + {% if config.isbn %}{% endif %} + {% block style %} + {% for resource in plugins.resources.css %} + {% if resource.url %} + + {% else %} + + {% endif %} + {% endfor %} + {% endblock %} + + {% block head %}{% endblock %} + + + {% block body %}{% endblock %} + {% block javascript %}{% endblock %} + + diff --git a/docs/cover.jpg b/docs/cover.jpg new file mode 100755 index 0000000..d68eeb1 Binary files /dev/null and b/docs/cover.jpg differ diff --git a/docs/cover_small.jpg b/docs/cover_small.jpg new file mode 100644 index 0000000..64872ab Binary files /dev/null and b/docs/cover_small.jpg differ diff --git a/docs/index.md b/docs/index.md deleted file mode 120000 index 75cc59e..0000000 --- a/docs/index.md +++ /dev/null @@ -1 +0,0 @@ -overview.md \ No newline at end of file diff --git a/docs/pictures/make-units.svg b/docs/pictures/make-units.svg index e998f3e..496aeff 100644 --- a/docs/pictures/make-units.svg +++ b/docs/pictures/make-units.svg @@ -1,11787 +1,1635 @@ - - - \ No newline at end of file + + \ No newline at end of file diff --git a/docs/resources/cover.svg b/docs/resources/cover.svg new file mode 100644 index 0000000..55509c7 --- /dev/null +++ b/docs/resources/cover.svg @@ -0,0 +1,212 @@ + + + + diff --git a/docs/resources/ebook.css b/docs/resources/ebook.css new file mode 100644 index 0000000..39f126c --- /dev/null +++ b/docs/resources/ebook.css @@ -0,0 +1,386 @@ +/* IoT.Bzh theaming */ + +h1 { + color: #330066; + border-bottom: 2px solid #330066; +} + +h2 { + color: #330066; +} + +h3 { + color: #330066; +} + +h4 { + color: #330066; +} + + +/* GENERAL ELEMENTS */ + +/* clear both */ + +.clear { + clear: both; +} + +.section> :last-child { + margin-bottom: 0 !important; +} + +.section> :first-child { + margin-top: 0 !important; +} + + +/* SPECIAL ELEMENTS */ + + +/* page break always after element on pdf/print definition */ + +div.pagebreak { + page-break-after: always; +} + + +/* no page break inside element on pdf/print definition */ + +div.nopb { + page-break-inside: avoid !important; + margin: 4px 0 4px 0; +} + + +/* note blocks */ + +div.note { + background: #FCF8E3 none repeat scroll 0% 0%; + color: #8A6D3B; + padding: 15px; + margin-bottom: 10px; + border-bottom: 5px solid #DDD; + border-color: #FAEBCC; + page-break-inside: avoid; +} + +div.note p { + padding-bottom: 0; + margin-bottom: 0; +} + + +/* images, figures and captions */ + +p img { + /* center all images */ + display: block; + margin: 0 auto; + padding: 10px 0; +} + +figure { + margin: 1.0em 0px; + padding: 10px 0; + text-align: center; + page-break-inside: avoid; + display: block; +} + +figure img { + display: block; + margin: 0 auto; +} + +figcaption { + clear: left; + margin: 1.0em 0 0 0; + text-align: center; + font-style: italic; + line-height: 1.5em; + font-size: 80%; + color: #666; + display: block; +} + +.page .section p img { + margin-top: 10px; +} + + +/* ul, ol list margin fix */ + +.page .section ol, +.page .section ul { + margin-bottom: 10px; +} + + +/* blockquotes */ + +.page .section blockquote { + margin: 0 0 0 5%; + font-style: italic; +} + + +/* PAGE SPECIFIC */ + + +/* set summary page to right side of the paper */ + +.page .toc h1 { + page-break-before: right; +} + +.page .section.toc { + page-break-inside: always; +} + +/* table headers */ + +div#README\.md table { + margin-top: 30px; + font-size: 95%; +} + +div#README\.md table thead { + display: none; +} + + + +/* CITATION AND IMAGES */ + + +/* math image styles */ + +.page .section p img.svg, +.page .section p img.png { + margin-top: 0px; + margin-bottom: -2px; +} + +.page .section p img.math { + vertical-align: middle; + height: auto; + width: auto; + margin-top: -4px; + max-height: 15px; +} + +.page .section p img.math.line1 { + margin-top: -7px; + max-height: 19px; +} + +.page .section p img.math.line2 { + margin-top: -1px; + max-height: 30px; +} + + +/* credits page */ + +.page .section ul.pictures { + margin-left: -30px; +} + +.page .section ul.pictures li { + list-style: outside none none; +} + +.page .section ul.pictures li a { + float: left; +} + +.page .section ul.pictures li span { + display: block; + margin-left: 100px; +} + + + +/* sub and super script */ + +.page .section sub { + font-size: 80%; + margin-left: 1px; +} + + +/* citations and references */ + +.page .section sup { + margin-left: -1px; + margin-right: 2px; + font-size: 80%; +} + +.page .section sup:before { + content: " "; +} + +.page .section ul.citations, +.page .section ul.references { + margin-left: -30px; +} + + +.page .section ul.citations li:nth-child(1) { + margin-top: 20px; + padding-top: 20px; + border-top: 1px solid #BBB; +} + +.page .section ul.citations li, +.page .section ul.references li { + list-style: outside none none; +} + +.page .section ul.citations li { + font-size: 80%; +} + +.page .section ul.citations li>span:nth-child(1), +.page .section ul.references li>span:nth-child(1) { + display: block; + float: left; + text-align: left; + width: 70px +} + +.page .section ul.citations li>span:nth-child(1) { + width: 50px +} + +.page .section ul.references li div { + margin-left: 70px; +} + +.page .section ul.citations li div { + margin-left: 50px; +} + +.page .section a[href="#"], +.page .section a[href="#"]:link, +.page .section a[href="#"]:visited, +.page .section a[href="#"]:hover, +.page .section a[href="#"]:focus { + text-decoration: none; + color: inherit; + cursor: text; + font-style: italic; +} + + +/* self referential footnotes */ + +.page .section div[type="selfref"] a[href="#"], +.page .section div[type="selfref"] a[href="#"]:link, +.page .section div[type="selfref"] a[href="#"]:visited, +.page .section div[type="selfref"] a[href="#"]:hover, +.page .section div[type="selfref"] a[href="#"]:focus { + font-style: normal; +} + +.page .section div[type="selfref"] span:nth-child(1) { + display: none; +} + + +/* page break always after element on pdf/print definition */ + +div.page-break { + page-break-inside: always; +} + +div.page-break:before { + content: ' '; +} + + +/* no page break inside element on pdf/print definition */ + +div.nopb { + page-break-inside: avoid; +} + +/* justify text */ +p { + text-align: justify; +} + +/* page header and footer */ + +.pdf-footer, +.pdf-header { + margin-top: 20px; + color: #aaa; +} + +.pdf-header .header-left { + float: left; + margin-left: 2em; + margin-right: auto; +} + +.pdf-header .header-right { + display: table; + margin-left: auto; + margin-right: 2em; +} + +.pdf-footer .sub { + padding-top: 8px; + font-size: 70%; +} + +.pdf-header .sub { + padding-top: 2px; + font-size: 70%; +} + +.pdf-footer { + padding-top: 10px; + border-top: 1px solid #eee; +} + +.pdf-footer .footer-left { + float: left; + margin-left: 2em; + margin-right: auto; +} + +.pdf-footer .footer-center { + display: table; + margin-left: auto; + margin-right: auto; +} + +.pdf-footer .footer-right { + float: right; + margin-left: auto; + margin-right: 2em; +} + +.pdf-header { + padding-bottom: 10px; + border-bottom: 1px solid #eee; +} + +.pdf-header .header-pages-count { + float: right; + text-align: right; +} + +.pdf-header .header-pages-count a, +.pdf-header .header-pages-count a:visited, +.pdf-header .header-pages-count a:active, +.pdf-header .header-pages-count a:focus, +.pdf-header .header-pages-count a:link { + text-decoration: none; + color: #aaa; + cursor: text; +} diff --git a/docs/resources/make_cover.sh b/docs/resources/make_cover.sh new file mode 100755 index 0000000..13ba4f0 --- /dev/null +++ b/docs/resources/make_cover.sh @@ -0,0 +1,26 @@ +#!/bin/bash +DOCS_DIR=$(cd $(dirname $0)/.. && pwd) +BOOKFILE=$DOCS_DIR/../book.json + +TITLE=$(grep '"title":' $BOOKFILE | cut -d'"' -f 4) +SUBTITLE="" +VERSION="Version $(grep '"version":' $BOOKFILE | cut -d'"' -f 4)" +DATE=$(grep '"published":' $BOOKFILE | cut -d'"' -f 4) + +[ -z "$TITLE" ] && { echo "Error TITLE not set!" ; exit 1; } +[ -z "$VERSION" ] && { echo "Error VERSION not set!" ; exit 1; } +[ -z "$DATE" ] && { echo "Error DATE not set!" ; exit 1; } + + +cat $(dirname $0)/cover.svg | sed -e "s/{title}/$TITLE/g" \ + -e "s/font-size:87.5px/font-size:54px/g" \ + -e "s/{subtitle}/$SUBTITLE/g" \ + -e "s/{version}/$VERSION/g" \ + -e "s/{date}/$DATE/g" \ + > /tmp/cover.svg + +# use imagemagick convert tool (cover size must be 1800x2360) +convert -resize "1600x2160!" -border 100 -bordercolor white -background white \ + -flatten -quality 100 /tmp/cover.svg $DOCS_DIR/cover.jpg + +convert -resize "200x262!" $DOCS_DIR/cover.jpg $DOCS_DIR/cover_small.jpg diff --git a/gendocs.sh b/gendocs.sh new file mode 100755 index 0000000..d96802c --- /dev/null +++ b/gendocs.sh @@ -0,0 +1,75 @@ +#!/bin/bash + +OUTFILENAME="Application-Framework-Service" + +SCRIPT=$(basename $BASH_SOURCE) + +function usage() { + cat <&2 +Usage: $SCRIPT [options] [pdf|serve|doxygen] + +Options: + --debug + enable debug when generating pdf or html documentation + -d|--dry + dry run + -h|--help + get this help + +Example: + $SCRIPT pdf + +EOF + exit 1 +} + +function info() { + echo "$@" >&2 +} + +#default values +DEBUG_FLAG="" +DRY="" +DO_ACTION="" +OUT_DIR=./build + +[[ $? != 0 ]] && usage +while [ $# -gt 0 ]; do + case "$1" in + --debug) DEBUG_FLAG="--log=debug --debug";; + -d|--dry) DRY=echo;; + -h|--help) usage;; + pdf | serve | doxygen) DO_ACTION=$1;; + --) break;; + esac + shift +done + +cd $(dirname $0) +ROOTDIR=`pwd -P` + +# Create out dir if needed +[ -d $OUT_DIR ] || mkdir -p $OUT_DIR + +if [ "$DO_ACTION" = "pdf" -o "$DO_ACTION" = "serve" ]; then + GITBOOK=`which gitbook` + [ "$?" = "1" ] && { echo "You must install gitbook first, using: sudo npm install -g gitbook-cli"; exit 1; } + + EBCONV=`which ebook-convert` + [ "$?" = "1" ] && { echo "You must install calibre first, using: 'sudo apt install calibre' or refer to https://calibre-ebook.com/download"; exit 1; } + + if [ "$DO_ACTION" = "pdf" ]; then + OUTFILE=$OUT_DIR/$OUTFILENAME.pdf + $DRY $GITBOOK pdf $ROOTDIR $OUTFILE $DEBUG_FLAG + [ "$?" = "0" ] && echo "PDF has been successfully generated in $OUTFILE" + else + $DRY $GITBOOK serve $DEBUG_FLAG + fi + +elif [ "$DO_ACTION" = "doxygen" ]; then + $DRY cd $OUT_DIR && cmake .. && make doxygen $ROOTDIR/Doxyfile + +else + echo "Unknown action !" + usage +fi diff --git a/mkdocs.yml b/mkdocs.yml index fc8cb09..8a63ec6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,7 +2,7 @@ site_name: AGL Application Framework theme: readthedocs docs_dir: docs pages: - - 'Overview' : 'index.md' + - 'Overview' : 'README.md' - 'Quick tutorial' : 'quick-tutorial.md' - 'The frameworks' : - 'The application framework': 'application-framework.md'

{{ page.title }}

{{ "SUMMARY"|t }}

{{ part.title }}