From a3e6126b082335cb9722c6b8d5321dd39d6d2dca Mon Sep 17 00:00:00 2001 From: Romain Forlot Date: Mon, 12 Jun 2017 09:36:44 +0200 Subject: Updating README and add usage documentation. Change-Id: I1bc2ef589ef60098cd1c1eb203e3140c0c955eed Signed-off-by: Romain Forlot --- README.md | 24 +-- book.json | 93 +++++++++ docs/1-Architecture.md | 21 ++ docs/2-Installation.md | 48 +++++ docs/3-Usage.md | 151 ++++++++++++++ docs/Doc-Revisions.md | 6 + docs/README.md | 8 + docs/SUMMARY.md | 8 + docs/_layouts/ebook/page.html | 36 ++++ docs/_layouts/ebook/pdf_footer.html | 13 ++ docs/_layouts/ebook/pdf_header.html | 13 ++ docs/_layouts/ebook/summary.html | 58 ++++++ docs/_layouts/layout.html | 28 +++ docs/cover.jpg | Bin 0 -> 225694 bytes docs/cover_small.jpg | Bin 0 -> 14655 bytes docs/images/high-level-arch.png | Bin 0 -> 30810 bytes docs/images/iotbzh_logo_small.png | Bin 0 -> 6989 bytes docs/images/logo_iot_bzh.svg | 142 +++++++++++++ docs/resources/cover.svg | 212 ++++++++++++++++++++ docs/resources/ebook.css | 386 ++++++++++++++++++++++++++++++++++++ docs/resources/make_cover.sh | 14 ++ gendocs.sh | 73 +++++++ 22 files changed, 1316 insertions(+), 18 deletions(-) create mode 100644 book.json create mode 100644 docs/1-Architecture.md create mode 100644 docs/2-Installation.md create mode 100644 docs/3-Usage.md create mode 100644 docs/Doc-Revisions.md create mode 100644 docs/README.md create mode 100644 docs/SUMMARY.md create mode 100644 docs/_layouts/ebook/page.html create mode 100644 docs/_layouts/ebook/pdf_footer.html create mode 100644 docs/_layouts/ebook/pdf_header.html create mode 100644 docs/_layouts/ebook/summary.html create mode 100644 docs/_layouts/layout.html create mode 100755 docs/cover.jpg create mode 100644 docs/cover_small.jpg create mode 100755 docs/images/high-level-arch.png create mode 100644 docs/images/iotbzh_logo_small.png create mode 100644 docs/images/logo_iot_bzh.svg create mode 100644 docs/resources/cover.svg create mode 100644 docs/resources/ebook.css create mode 100755 docs/resources/make_cover.sh create mode 100755 gendocs.sh diff --git a/README.md b/README.md index a96c30d..3711156 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,23 @@ # High level binding -CAN binder, based upon ViWi definition. +CAN binding, based upon ViWi definition. This binding is intended to act between the low-level binding and clients. It collects resources as defined in a json configuration file, and implements subscribe/unsubscribe/get verbs for the clients. # build ```bash -git submodule init -git submodule update -mkdir build -cd build -cmake .. -make +mkdir build;cd build; cmake ..; make ``` - -> ! WARNING don't forget to initialize submodule needed to build the project. - # launching natively under linux you can launch afb-daemon with the low-level and high-level bindings with a command like: ```bash -afb-daemon --rootdir=/CAN-binder/build/package --ldpaths=/CAN-binder/build/package/lib:/build/high-can-binding --port=1234 --tracereq=common --token=1 --verbose --verbose --verbose +afb-daemon --rootdir=/CAN-binder/build/package --ldpaths=/CAN-binder/build/package/lib:/build/high-can-binding --port=1234 --tracereq=common --token=1 --verbose ``` #json configuration file -json configuration file (high.json) must be placed in the directory where you will launch afb-dameon +json configuration file (high.json) must be placed in the directory where you launch afb-dameon The json configuration file consists in 2 sections: ## definitions section @@ -101,12 +93,8 @@ For instance: } ``` # Running and testing -You can use afb-client-demo to test high level binding. -For instance, once daemon has been launched with the 2 bindings: -```bash -afb-client-demo ws://localhost:1234/api?token=1 -``` -You can then use commands such as: +You can use *afb-client-demo* to test high level binding. +For instance, once daemon has been launched with the 2 bindings, you can use commands such as: ```bash high-can subscribe {"name":"/car/doors/","interval":10000} high-can unsubscribe {"name":"/car/doors/","interval":10000} diff --git a/book.json b/book.json new file mode 100644 index 0000000..a39312a --- /dev/null +++ b/book.json @@ -0,0 +1,93 @@ +{ + "title": "High Level CAN Binding Guide", + "description": "High level CAN bus binding, based upon ViWi definition.", + "keywords": "AGL, Development, CAN, binding, binder, ViWi", + "author": "IoT.Bzh Team", + "website": "http://iot.bzh", + "published": "June 2017", + "version": "1.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, 3], + "hidepagefooters": [2, 3], + + "plugins": [ + "regexplace" + ], + "pluginsConfig": { + "regexplace": { + "removeFirstPartsInSectionNumber": true, + "substitutes": [{ + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "!\\[(.*?)\\]\\((.*?)(?:\\s+\"(.*)\")?\\){0,}{caption=1([^\\}]*)}", + "flags": "gmi", + "substitute": "
\"$1\"
", + "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-Architecture.md b/docs/1-Architecture.md new file mode 100644 index 0000000..487c467 --- /dev/null +++ b/docs/1-Architecture.md @@ -0,0 +1,21 @@ +# AGL VIWI HIGH-CAN binding architecture + +This binding is intended to act between low-level binding(s) and clients. It builds ViWi resources as defined in a json configuration file, and implements subscribe/unsubscribe/get verbs for the clients. Each ViWi resource can be composed of several elements, for which subscriptions will be made to the low-level binding with configurable frequencies or filters. + +![ViWi High Level binding architecture](images/high-level-arch.png) + + + +## BRIEF VIWI DESCRIPTION + +ViWi (Volkswagen Infotainment Web Interface) protocol defines a serie of objects, which can be queried or updated via JSon messages. + +Each object is assigned with a unique URI. + +The depth of the URI tree is limited to 3, i.e. /service/resource>/element/, for instance **/car/doors/3901a278-ba17-44d6-9aef-f7ca67c04840**. + +To retrieve the list of elements for a given resource, one can use the get command, for instance **get /car/doors/**. + +It is also possible to subscribe to elements or group of elements, for instance **subscribe /car/doors/3901a278-ba17-44d6-9aef-f7ca67c04840**. Requests can also have various filters, or specify a frequency. + +More details in the [ViWi general documentation](https://www.w3.org/Submission/viwi-protocol/) and in the [ViWi.service.car documentation](https://www.w3.org/Submission/viwi-service-car/) diff --git a/docs/2-Installation.md b/docs/2-Installation.md new file mode 100644 index 0000000..a5e1265 --- /dev/null +++ b/docs/2-Installation.md @@ -0,0 +1,48 @@ +## Installation + +## Prerequisites + +Low CAN binding must be installed. Prerequisites are the same. + +```bash +$ git clone https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service +``` + +## Clone and build high level binding + +### Build requirements + +* CMake version 3.0 or later +* G++, Clang++ or any C++11 compliant compiler. + +### Clone + +```bash +$ export WD=$(pwd) +$ git clone https://github.com/iotbzh/high-level-viwi-service.git +``` + +### Build + +```bash +$ cd $WD/high-level-viwi-service +$ mkdir build +$ cd build +$ cmake .. +$ make +``` + +## Launching + +The Json high level configuration file *high.json* must be placed in the directory where you launch afb-daemon. + +```bash +$ cp $WD/high-level-viwi-service/high.json $WD +$ cd $WD +``` +Natively under linux you can launch afb-daemon with the low-level and high-level bindings with a command like: + +```bash +$ cd $WD +$ afb-daemon --rootdir=$WD/low-level-can-service/CAN-binder/build/package --ldpaths=$WD/low-level-can-service/CAN-binder/build/package/lib:$WD/high-level-viwi-service/build/high-can-binding --port=1234 --tracereq=common --token=1 --verbose +``` diff --git a/docs/3-Usage.md b/docs/3-Usage.md new file mode 100644 index 0000000..450b459 --- /dev/null +++ b/docs/3-Usage.md @@ -0,0 +1,151 @@ +# Usage + +## JSon configuration file + +This file must be named *high.json*, and must accessible from afb-daemon. +The json configuration file consists in 2 sections: + +### Definitions section + +This section describes each resources defined in the high-level binding. Each resource is composed with different properties having a name, a type and a description. +Type can be boolean, double, string, or int. Properties "id", "uri" and "name" are compulsory. + +For instance: + +```json +{ + "name": "/car/demoboard/", + "properties": { + "id": { + "type": "string", + "description": "identifier" + }, + "uri": { + "type": "string", + "description": "object uri" + }, + "name": { + "type": "string", + "description": "name" + }, + "unit": { + "type": "string", + "description": "units" + }, + "speed": { + "type": "double", + "description": "vehicle centerpoint speed as shown by the instrument cluster" + }, + "rpm": { + "type": "double", + "description": "engine rotations per minute" + }, + "level": { + "type": "double", + "description": "level of tankage" + }, + "load": { + "type": "double", + "description": "engine load" + } + } +} +``` + + + +### Resources section + +This section defines which values should be assigned to resource's properties as defined in the definitions section. +The link to the definitions section is made through the name of the resource. + +Some values are static, some are linked to low-level requests. + +In case a value is linked to a low-level request, the value will start with "${" and end with "}". In that case the value will consist in the name of the low-level signal, followed +with the frequency of the signal in ms. -1 in the frequency means that high level binding should subscribe to low level binding for all changes, without specifying a frequency. + +For instance: +```json +{ + "name": "/car/demoboard/", + "values": [{ + "name": "vehicleSpeed", + "unit": "km/h", + "speed": "${diagnostic_messages.vehicle.speed,1000}" + }, { + "name": "engineSpeed", + "unit": "rpm", + "rpm": "${diagnostic_messages.engine.speed,1000}" + }, { + "name": "fuelLevel", + "unit": "litre", + "level": "${diagnostic_messages.fuel.level,1000}" + }, { + "name": "engineLoad", + "unit": "Nm", + "load": "${diagnostic_messages.engine.load,1000}" + }] +} +``` + + + +## Running and testing + +### Launch the binder together with the two bindings + +```bash +$ cd $WD +$ afb-daemon --rootdir=$WD/low-level-can-service/CAN-binder/build/package --ldpaths=$WD/low-level-can-service/CAN-binder/build/package/lib:$WD/high-level-viwi-service/build/high-can-binding --port=1234 --tracereq=common --token=1 --verbose +``` + +### Use afb-client-demo to test high level binding + +On another terminal, connect to the binding using previously installed _**AFB Websocket CLI**_ tool: + +```bash +$ afb-client-demo ws://localhost:1234/api?token=1 +``` + +You will be on an interactive session where you can communicate directly with the binding API. + +The binding provides at this moment 3 verbs, _get_, _subscribe_ and _unsubscribe_, which can take a JSON object as an argument. + + +To use the _**AFB Websocket CLI**_ tool, a command line will be like the following : + +``` + +``` + +Where: + +* API : _**high-can**_. +* Verb : _**get**_, _**subscribe**_ or _**unsubscribe**_ +* Arguments : _**{ "name": "/car/doors/" }**_ + +You can therefore use commands such as: + +``` +high-can subscribe {"name":"/car/doors/","interval":10000} +high-can unsubscribe {"name":"/car/doors/","interval":10000} +high-can get {"name":"/car/demoboard/"} +high-can get {"name":"/car/demoboard/","fields":["fuelLevel","engineLoad"]} +``` + +For instance the output of the third command should be: + +``` +high-can get {"name":"/car/demoboard/"} +ON-REPLY 1:high-can/get: {"response":{"\/car\/demoboard\/2159e2-5b638a-39e242-7a2f5":{"id":"2159e2-5b638a-39e242-7a2f5","name":"vehicleSpeed","speed":0.000000,"unit":"km\/h","uri":"\/car\/demoboard\/2159e2-5b638a-39e242-7a2f5"},"\/car\/demoboard\/22ad2c-5a3c2b-50fabb-324c82":{"id":"22ad2c-5a3c2b-50fabb-324c82","level":0.000000,"name":"fuelLevel","unit":"litre","uri":"\/car\/demoboard\/22ad2c-5a3c2b-50fabb-324c82"},"\/car\/demoboard\/3a3ab9-2bd52c-11d30-689acf":{"id":"3a3ab9-2bd52c-11d30-689acf","name":"engineSpeed","rpm":0.000000,"unit":"rpm","uri":"\/car\/demoboard\/3a3ab9-2bd52c-11d30-689acf"},"\/car\/demoboard\/5ae808-8093cb-99716-30a605":{"id":"5ae808-8093cb-99716-30a605","load":0.000000,"name":"engineLoad","unit":"Nm","uri":"\/car\/demoboard\/5ae808-8093cb-99716-30a605"}},"jtype":"afb-reply","request":{"status":"success","uuid":"44ce03f9-a7ca-49e1-a62a-40c74db0caa0"}} +``` + +As you can see for the moment all values are 0, because we didn't inject any CAN data in the binder. To do this, you can use **canplayer** to feed the bindings with some data. + +For instance, on a third terminal: + +```bash +$ canplayer -I highwaycomplete +``` + + diff --git a/docs/Doc-Revisions.md b/docs/Doc-Revisions.md new file mode 100644 index 0000000..1de1abb --- /dev/null +++ b/docs/Doc-Revisions.md @@ -0,0 +1,6 @@ +Document revisions +================== + +| Date | Version | Designation  | Author | +|-------------|---------|--------------------------------------|-------------------------| +| 07 Jun 2017 | 1.0 | Initial release | P. Lelong [ Iot.bzh ] | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f22761a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,8 @@ +# Abstract + +This project proposes a High Level CAN Binding for AGL, with the following features: + +* Interface between UI and Low Level CAN binding +* Generation of ViWi resources based on a json configuration description +* Connection to Low Level binding in order to maintain Viwi objects status +* Accepts subscriptions and gets events, and generate in reply Json messages in ViWi format diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..504de46 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,8 @@ +# Summary + +* [Abstract](README.md) +* [Document revisions](Doc-Revisions.md) +* [Architecture](1-Architecture.md) +* [Installation](2-Installation.md) +* [Usage](3-Usage.md) + 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.title }}

+
+ {{ 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 %} +
    +

    {{ "SUMMARY"|t }}

    +
      + {% for part in summary.parts %} + {% if part.title %} +
    1. +

      {{ part.title }}

      +
      2. + {% endif %} + {{ articles(part.articles) }} + + {% if not loop.last %} +
    2. + {% endif %} + {% endfor %} + + {% if glossary.path %} +
    3. + + {{ "GLOSSARY"|t }} + +
      4. + {% endif %} +
    +
    +{% 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..48e28ad 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..00c358b Binary files /dev/null and b/docs/cover_small.jpg differ diff --git a/docs/images/high-level-arch.png b/docs/images/high-level-arch.png new file mode 100755 index 0000000..b4a1e8c Binary files /dev/null and b/docs/images/high-level-arch.png differ diff --git a/docs/images/iotbzh_logo_small.png b/docs/images/iotbzh_logo_small.png new file mode 100644 index 0000000..6a98c60 Binary files /dev/null and b/docs/images/iotbzh_logo_small.png differ diff --git a/docs/images/logo_iot_bzh.svg b/docs/images/logo_iot_bzh.svg new file mode 100644 index 0000000..aa23e84 --- /dev/null +++ b/docs/images/logo_iot_bzh.svg @@ -0,0 +1,142 @@ + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + IOT + + BZH + + + + 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 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + {title} {subtitle} {version} {date} + 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..fef2087 --- /dev/null +++ b/docs/resources/make_cover.sh @@ -0,0 +1,14 @@ +#!/bin/bash + +cat cover.svg | sed -e 's/{title}/Low Level CAN binding/' \ + -e 's/font-size:87.5px/font-size:50px/g' \ + -e 's/{subtitle}//g' \ + -e 's/{version}/Version 1.0/g' \ + -e 's/{date}/March 2017/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 ../cover.jpg + +convert -resize "200x262!" ../cover.jpg ../cover_small.jpg diff --git a/gendocs.sh b/gendocs.sh new file mode 100755 index 0000000..a0f6e5c --- /dev/null +++ b/gendocs.sh @@ -0,0 +1,73 @@ +#!/bin/bash + +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/LowLevelCanBinding_Guide.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 -- cgit 1.2.3-korg