diff options
| -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.md | 68 |
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 +``` |