summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/handle-docs/handle-docs.md104
-rw-r--r--docs/handle-docs/simple-book.yml68
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%/"