handle-docs: add documentation for book worflow

Change-Id: I893751d12cb787861a4fbac03ebe463b22a07bc8
Signed-off-by: Clément Bénier <clement.benier@iot.bzh>

2 files changed, 172 insertions, 0 deletions

diff --git a/docs/handle-docs/handle-docs.md b/docs/handle-docs/handle-docs.md
new file mode 100644
index 0000000..9f3c522
--- /dev/null
+++ b/docs/handle-docs/handle-docs.md
@@ -0,0 +1,104 @@
+# How to add markdown files to AGL documentation
+
+This documentation helps you to add new markdown files to AGL documentation.
+They are two steps to add new markdown files to AGL documentation:
+
+- Add a book yaml file to the repository where the markdown files are.
+- Add an entry into the section yaml file that point to your book file. The section yaml file is in docs-webtemplate repository (git@github.com:automotive-grade-linux/docs-webtemplate.git) named ```section_<version>.yml```.
+
+---
+
+**Note**: To generate a local documentation please refer to the README of the docs-webtemplate (https://github.com/automotive-grade-linux/docs-webtemplate) and use the script ```setupdocs.sh```.
+
+---
+
+## Add a book yaml file into repository
+
+The book file is needed to describe your documentation.
+There are several types of book:
+
+- book
+- api
+
+### Book Type
+
+The book type describes documentation chapters.
+Below the generic way to include a book file:
+
+```yaml
+type: books
+books:
+-
+    id: <ID1>
+    order: x #optional: between 0 in 100 default is 50, it allows to define order in final          #documentation, more the order number is low more the documentation is first
+    title: title of your chapter  #default title
+    title_<lang>: title in <lang>
+    description: description of your book
+    keywords: some keywords
+    author: author of the documentation
+    version: version of the documentation
+    chapters:
+        - name: Name of your subchapter
+          name_<lang>: Name of your subchapter in <lang>
+            url: "%lang%/softlink/to/your/mardown.md" #%lang% will be replaced by the
+                                                      #available languages,
+                                                      #default language can be in the root directory
+        - name: Name of your subchapter
+          name_<lang>: Name of your subchapter in <lang>
+          url: "%lang%/softlink/to/your/mardown.md"
+        - name: Name of your subchapter
+          name_<lang>: Name of your subchapter in <lang>
+            - name: Name of your subsubchapter
+              name_<lang>: Name of your subsubchapter in <lang>
+              url: "%lang%/softlink/to/your/mardown.md"
+            - name: Name of your subsubchapter
+              name_<lang>: Name of your subsubchapter in <lang>
+              children:
+                - ...
+            - ...
+        - ...
+-
+    id: <ID2>
+    ...
+```
+
+Here a simple yaml file, you can start from :
+
+```bash
+wget https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/handle-docs/simple-book.yml
+```
+
+### Api Type
+
+In progress
+
+## Add an entry in section file
+
+There are 4 sections in docs: getting_started, architecture_guides, developer_guides, apis_services.
+
+They are located in content/docs in docs-webtemplate repository. In addition, each directory contains several section yaml file, one a version. For master version, it is ```section_master.yml```.
+
+Below the structure of section yaml file.
+
+```yaml
+url_fetch : DEFAULT_URL_FETCH #this the default url_fetch that can be overload further, there already are some default variables defined in docs-webtemplate/docs-tools
+git_commit : DEFAULT_VERSION #this is the default git_commit that can be overload further, there already are some default variables defined in docs-webtemplate/docs-tools
+
+name: Name of the section
+template: generated_index.html
+books:
+-
+    id: <ID1>
+    url_fetch: <url_fetch> #optional, overload the default one
+    git_commit: <git_commit> #optional, overload the default one
+    path: "softpath/from/root/repository/to/the/book/yaml/file"
+    books: #optional: subbooks, will be a child of the above book
+        - id: <SUBID2>
+          url_fetch: <url_fetch> #optional, overload the default one
+          git_commit: <git_commit> #optional, overload the default one
+          path: "softpath/from/root/repository/to/the/book/yaml/file"
+        - ...
+-
+    id: <ID2>
+    ...
+```
\ No newline at end of file
diff --git a/docs/handle-docs/simple-book.yml b/docs/handle-docs/simple-book.yml
new file mode 100644
index 0000000..ebee034
--- /dev/null
+++ b/docs/handle-docs/simple-book.yml
@@ -0,0 +1,68 @@
+type: books
+books:
+-
+    id:
+    order:  #optional
+    title:
+    title_fr: #optionnal
+    title_jp: #optionnal
+    description:
+    keywords:
+    author:
+    version:
+    chapters:
+    - name:
+      name_fr: #optional
+      name_jp: #optional
+      url: "%lang%/"
+    - name:
+      name_fr: #optional
+      name_jp: #optional
+      children: #optional
+        - name:
+          name_fr: #optional
+          name_jp: #optional
+          url: "%lang/"
+        - name:
+          name_fr: #optional
+          name_jp: #optional
+          children: #optional
+            - name:
+              name_fr: #optional
+              name_jp: #optional
+    - name:
+      name_fr: #optional
+      url: "%lang%/"
+-
+    id:
+    order:  #optional
+    title:
+    title_fr: #optionnal
+    title_jp: #optionnal
+    description:
+    keywords:
+    author:
+    version:
+    chapters:
+    - name:
+      name_fr: #optional
+      name_jp: #optional
+      url: "%lang%/"
+    - name:
+      name_fr: #optional
+      name_jp: #optional
+      children: #optional
+        - name:
+          name_fr: #optional
+          name_jp: #optional
+          url: "%lang/"
+        - name:
+          name_fr: #optional
+          name_jp: #optional
+          children:
+            - name:
+              name_fr: #optional
+              name_jp: #optional
+    - name:
+      name_fr: #optional
+      url: "%lang%/"