From 752e486dca789d1790d92330c7869a3f3e624591 Mon Sep 17 00:00:00 2001 From: Sebastien Douheret Date: Wed, 5 Dec 2018 11:57:28 +0100 Subject: handle-docs: add more details about book.yml workflow Change-Id: I47fb5bedf6d1e70c0f5e2607bf67b3947b210b1c Signed-off-by: Sebastien Douheret --- docs/handle-docs/book.yml.in | 68 ++++++++++++++++++++++++++++++++++++++++ docs/handle-docs/handle-docs.md | 68 ++++++++++++++++++++++++++-------------- docs/handle-docs/simple-book.yml | 68 ---------------------------------------- 3 files changed, 113 insertions(+), 91 deletions(-) create mode 100644 docs/handle-docs/book.yml.in delete mode 100644 docs/handle-docs/simple-book.yml diff --git a/docs/handle-docs/book.yml.in b/docs/handle-docs/book.yml.in new file mode 100644 index 0000000..52e8eb7 --- /dev/null +++ b/docs/handle-docs/book.yml.in @@ -0,0 +1,68 @@ +type: books +books: +- + id: + order: #optional + title: + title_fr: #optional + title_jp: #optional + 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: #optional + title_jp: #optional + 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%/" 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). + + + +## 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_.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_.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 + + -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: - 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_: title in description: description of your book @@ -40,17 +58,17 @@ books: chapters: - name: Name of your subchapter name_: Name of your subchapter in - 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_: Name of your subchapter in - url: "%lang%/softlink/to/your/mardown.md" + url: "%lang%/relative-path/to/your/mardown.md" - name: Name of your subchapter name_: Name of your subchapter in - name: Name of your subsubchapter name_: Name of your subsubchapter in - url: "%lang%/softlink/to/your/mardown.md" + url: "%lang%/relative-path/to/your/mardown.md" - name: Name of your subsubchapter name_: Name of your subsubchapter in 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: url_fetch: #optional, overload the default one 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: url_fetch: #optional, overload the default one 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: ... -``` \ No newline at end of file +``` diff --git a/docs/handle-docs/simple-book.yml b/docs/handle-docs/simple-book.yml deleted file mode 100644 index ebee034..0000000 --- a/docs/handle-docs/simple-book.yml +++ /dev/null @@ -1,68 +0,0 @@ -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%/" -- cgit 1.2.3-korg