1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
# 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).
See below a scheme of the workflow of agl documentation website generation.
As you can see, the section_``version``.yml contains the links to all the book yaml files, it is proceed to fetch all book yaml files from remote repositories to the docs-webtemplate. The book yaml files contains all the url to your markdown files from the remote repository.
As soon as all the markdown files are fetched, the tools process to generate the AGL doc website.
---
**Note:**
The images described in markdown files are automatically fetched. For that, the necessary condition is that in markdown files, the relative path has to match with the location of images.
---
## How to add a new documentation section into AGL documentation
They are two steps to add new markdown files to AGL documentation:
- 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](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 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
---
**Note:**
Multi-language is handled by key suffixes. That is to say, there are some keys that can be suffixed by a language: ``<key>_<lang>``
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.
A example for the french:
```
name: "My section in english"
name_fr: "Ma section en français"
url: "%lang/section.md"
```
```
$ ls -lR mydir
book.yml
section.md
fr/section.md
```
---
There are several types of book:
- book
- api
#### Book Type
`book` type describes documentation structure and chapters.
Below the generic way to include a book file:
```yaml
type: books
books:
-
id: <ID1>
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
keywords: some keywords
author: author of the documentation
version: version of the documentation
chapters:
- name: Name of your subchapter
name_<lang>: Name of your subchapter in <lang>
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%/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%/relative-path/to/your/mardown.md"
- name: Name of your subsubchapter
name_<lang>: Name of your subsubchapter in <lang>
children:
- ...
- ...
- ...
-
id: <ID2>
...
```
[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-next/docs/getting-started-book.yml -O my-new-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](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.
```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: <ID1>
url_fetch: <url_fetch> #optional, overload the default one
git_commit: <git_commit> #optional, overload the default one
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: "relativepath/from/root/repository/to/the/book/yaml/file"
- ...
-
id: <ID2>
...
```
|
