docs/5_How_To/3_How_to_add_documentation_to_AGL.md

   1 ---
   2 edit_link: ''
   3 title: How to add documentation to AGL
   4 origin_url: >-
   5   https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/handle-docs/handle-docs.md
   6 ---
   7
   8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/howto/master/howto-add-docs-handle-docs-book.yml -->
   9
  10 # How to add a new documentation section into AGL documentation
  11
  12 They are two steps to add new markdown files to AGL documentation:
  13
  14 - Add a book yaml file to the repository where the documentation sources are located (written in markdown files).
  15 - 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`.
  16
  17 ---
  18
  19 **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.
  20
  21 ---
  22
  23 ## Add a book yaml file into a repository
  24
  25 The book file is needed to describe how your documentation is structured and must be used to describe
  26 among others :
  27
  28 - the global title of the doc
  29 - the chapter name when the doc will be part of the whole documentation website
  30 - subchapters list and consequently subchapters hierarchy
  31 - multi-language description
  32
  33 ---
  34
  35 **Note:**
  36
  37 Multi-language is handled by key suffixes. That is to say, there are some keys that can be suffixed by a language: ``<key>_<lang>``
  38 For the url to the markdown files, the prefix ```%lang%``` will match with suffixes. So, you have to create a subdirectory named ```%lang%``` where the markdown files are put.
  39
  40 A example for the french:
  41
  42 ```
  43 name: "My section in english"
  44 name_fr: "Ma section en français"
  45 url: "%lang/section.md"
  46 ```
  47
  48 ```
  49 $ ls -lR mydir
  50 book.yml
  51 section.md
  52 fr/section.md
  53 ```
  54
  55 ---
  56
  57 There are several types of book:
  58
  59 - book
  60 - api
  61
  62 ### Book Type
  63
  64 `book` type describes documentation structure and chapters.
  65 Below the generic way to include a book file:
  66
  67 ```yaml
  68 type: books
  69 books:
  70 -
  71     id: <ID1>
  72     order: x #optional: between 0 in 100 default when not set is 50, it allows to define order in final
  73              #documentation, more the order number is low more the documentation is first
  74     title: title of your chapter  #default title
  75     title_<lang>: title in <lang>
  76     description: description of your book
  77     keywords: some keywords
  78     author: author of the documentation
  79     version: version of the documentation
  80     chapters:
  81         - name: Name of your subchapter
  82           name_<lang>: Name of your subchapter in <lang>
  83             url: "%lang%/relative-path/to/your/mardown.md" #%lang% will be replaced by the
  84                                                            #available languages,
  85                                                            #default language can be in the root directory
  86         - name: Name of your subchapter
  87           name_<lang>: Name of your subchapter in <lang>
  88           url: "%lang%/relative-path/to/your/mardown.md"
  89         - name: Name of your subchapter
  90           name_<lang>: Name of your subchapter in <lang>
  91             - name: Name of your subsubchapter
  92               name_<lang>: Name of your subsubchapter in <lang>
  93               url: "%lang%/relative-path/to/your/mardown.md"
  94             - name: Name of your subsubchapter
  95               name_<lang>: Name of your subsubchapter in <lang>
  96               children:
  97                 - ...
  98             - ...
  99         - ...
 100 -
 101     id: <ID2>
 102     ...
 103 ```
 104
 105 [book.yml.in](https://github.com/automotive-grade-linux/docs-sources/blob/master/docs/handle-docs/book.yml.in)
 106 is a sort of schema of book.yml. This file contains all supported keys.
 107
 108 Here a sample yaml file, you can start from :
 109
 110 ```bash
 111 wget https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master-next/docs/getting-started-book.yml -O my-new-book.yml
 112 ```
 113
 114 ### Api Type
 115
 116 In progress
 117
 118 ## Add an entry in section file
 119
 120 There are 4 sections in docs: getting_started, architecture_guides, developer_guides, apis_services.
 121
 122 They are located in `content/docs` in [docs-webtemplate](https://github.com/automotive-grade-linux/docs-webtemplate) repository.
 123 In addition, each directory contains several section yaml file, one a version. For master version, it is `section_master.yml`.
 124
 125 Below the structure of section yaml file.
 126
 127 ```yaml
 128 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
 129 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
 130
 131 name: Name of the section
 132 template: generated_index.html
 133 books:
 134 -
 135     id: <ID1>
 136     url_fetch: <url_fetch> #optional, overload the default one
 137     git_commit: <git_commit> #optional, overload the default one
 138     path: "relativepath/from/root/repository/to/the/book/yaml/file"
 139     books: #optional: subbooks, will be a child of the above book
 140         - id: <SUBID2>
 141           url_fetch: <url_fetch> #optional, overload the default one
 142           git_commit: <git_commit> #optional, overload the default one
 143           path: "relativepath/from/root/repository/to/the/book/yaml/file"
 144         - ...
 145 -
 146     id: <ID2>
 147     ...
 148 ```