summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorSebastien Douheret <sebastien.douheret@iot.bzh>2018-12-05 11:57:28 +0100
committerClément Bénier <clement.benier@iot.bzh>2019-01-29 14:49:16 +0100
commit752e486dca789d1790d92330c7869a3f3e624591 (patch)
treeccaaaa5dd90717ec17321ad24a813bc17264d968 /docs
parent87b8220dc0e23636eba08f2710728db4a98d163c (diff)
handle-docs: add more details about book.yml workflow
Change-Id: I47fb5bedf6d1e70c0f5e2607bf67b3947b210b1c Signed-off-by: Sebastien Douheret <sebastien.douheret@iot.bzh>
Diffstat (limited to 'docs')
-rw-r--r--docs/handle-docs/book.yml.in (renamed from docs/handle-docs/simple-book.yml)8
-rw-r--r--docs/handle-docs/handle-docs.md68
2 files changed, 49 insertions, 27 deletions
diff --git a/docs/handle-docs/simple-book.yml b/docs/handle-docs/book.yml.in
index ebee034..52e8eb7 100644
--- a/docs/handle-docs/simple-book.yml
+++ b/docs/handle-docs/book.yml.in
@@ -4,8 +4,8 @@ books:
id:
order: #optional
title:
- title_fr: #optionnal
- title_jp: #optionnal
+ title_fr: #optional
+ title_jp: #optional
description:
keywords:
author:
@@ -37,8 +37,8 @@ books:
id:
order: #optional
title:
- title_fr: #optionnal
- title_jp: #optionnal
+ title_fr: #optional
+ title_jp: #optional
description:
keywords:
author:
diff --git a/docs/handle-docs/handle-docs.md b/docs/handle-docs/handle-docs.md
index 9f3c522..c0ade95 100644
--- a/docs/handle-docs/handle-docs.md
+++ b/docs/handle-docs/handle-docs.md
@@ -1,28 +1,45 @@
-# How to add markdown files to AGL documentation
+# Abstract
+
+AGL doc website is based on a collection of markdown files fetched from various repositories.
+A tool available in [docs-tools](https://github.com/automotive-grade-linux/docs-tools) takes
+care of collecting and templating all markdown files according fetched_files.yml located in
+[docs-webtemplate](https://github.com/automotive-grade-linux/docs-webtemplate).
+
+<!-- TODO add SCHEMA + description of fetched_files.yml and book.yml logic -->
+
+## How to add a new documentation section into 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```.
+- Add a book yaml file to the repository where the documentation sources are located (written in markdown files).
+- Add an entry into the global section yaml file that point to your book file. The section yaml file is in [docs-webtemplate](https://github.com/automotive-grade-linux/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```.
+**Note**: To generate a local documentation please refer to the [README](https://github.com/automotive-grade-linux/docs-webtemplate/blob/master-next/README.md) of the docs-webtemplate (https://github.com/automotive-grade-linux/docs-webtemplate) and use `setupdocs.sh` script.
---
-## Add a book yaml file into repository
+### Add a book yaml file into a repository
+
+The book file is needed to describe how your documentation is structured and must be used to describe
+among others :
+
+- the global title of the doc
+- the chapter name when the doc will be part of the whole documentation website
+- subchapters list and consequently subchapters hierarchy
+- multi-language description
+
+<!-- TODO: Add more explanation of multi-language support (eg. suffix xxx_en, xxx_jp ) -->
-The book file is needed to describe your documentation.
There are several types of book:
- book
- api
-### Book Type
+#### Book Type
-The book type describes documentation chapters.
+`book` type describes documentation structure and chapters.
Below the generic way to include a book file:
```yaml
@@ -30,7 +47,8 @@ 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
+ order: x #optional: between 0 in 100 default when not set 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
@@ -40,17 +58,17 @@ books:
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
+ url: "%lang%/relative-path/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"
+ url: "%lang%/relative-path/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"
+ url: "%lang%/relative-path/to/your/mardown.md"
- name: Name of your subsubchapter
name_<lang>: Name of your subsubchapter in <lang>
children:
@@ -62,21 +80,25 @@ books:
...
```
-Here a simple yaml file, you can start from :
+[book.yml.in](https://github.com/automotive-grade-linux/docs-sources/blob/master/docs/handle-docs/book.yml.in)
+is a sort of schema of book.yml. This file contains all supported keys.
+
+Here a sample yaml file, you can start from :
```bash
-wget https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/handle-docs/simple-book.yml
+wget https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master-next/docs/getting-started-book.yml -O my-new-book.yml
```
-### Api Type
+#### Api Type
In progress
-## Add an entry in section file
+### 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```.
+They are located in `content/docs` in [docs-webtemplate](https://github.com/automotive-grade-linux/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.
@@ -91,14 +113,14 @@ 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"
+ path: "relativepath/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"
+ path: "relativepath/from/root/repository/to/the/book/yaml/file"
- ...
-
id: <ID2>
...
-``` \ No newline at end of file
+```