From 60ab592005f43243e993708a9c62b5733b53e768 Mon Sep 17 00:00:00 2001 From: Clément Bénier Date: Mon, 3 Dec 2018 18:38:21 +0100 Subject: handle-docs: add documentation for book worflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: I893751d12cb787861a4fbac03ebe463b22a07bc8 Signed-off-by: Clément Bénier --- docs/handle-docs/handle-docs.md | 104 +++++++++++++++++++++++++++++++++++++++ docs/handle-docs/simple-book.yml | 68 +++++++++++++++++++++++++ 2 files changed, 172 insertions(+) create mode 100644 docs/handle-docs/handle-docs.md create mode 100644 docs/handle-docs/simple-book.yml 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_.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: + 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_: title in + 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_: 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 + - name: Name of your subchapter + name_: Name of your subchapter in + url: "%lang%/softlink/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" + - name: Name of your subsubchapter + name_: Name of your subsubchapter in + children: + - ... + - ... + - ... +- + id: + ... +``` + +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: + url_fetch: #optional, overload the default one + 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: + url_fetch: #optional, overload the default one + git_commit: #optional, overload the default one + path: "softpath/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 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%/" -- cgit 1.2.3-korg