blob: 4da6165403d52b30a9eacf69923dc87d5ebffbfd (
plain)
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
|
---
title: Adding Documentation
---
The [documentation gerrit
repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation)
contains AGL documentation website template and content, rendering is visible at
[https://docs.automotivelinux.org](https://docs.automotivelinux.org).
The documentation site is hosted on
[readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and
corresponding builds are mentioned
[here](https://readthedocs.org/projects/automotivegradelinux/builds/).
## Download Repository
Clone with commit-msg hook :
```sh
$ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 <LFID>@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/"
```
## Building a local site
1. Change into the directory
```sh
$ cd documentation
```
2. Install MkDocs and rtd-dropdown theme
```sh
$ sudo pip install -r requirements.txt
```
3. If pip is not already installed then install it
```sh
$ sudo apt-install python3-pip
```
4. Serve locally (default rendered at [127.0.0.1:8000/](127.0.0.1:8000/)):
```sh
$ sudo mkdocs serve
```
Process to **add new or edit existing** markdown files to AGL documentation:
## Directory Structure
Find existing or add new markdowns in the following directory structure.
```sh
documentation
├── docs
│ ├── 1_Getting_Started
│ │ ├── 1_Quickstart
│ │ └── 2_Building_AGL_Image
| ├── .....
| |
| ├──<Chapter_Number>_<Chapter_Name>
| | ├──<Subchapter_Number>_<Subchapter_Name>
| | | ├──<Index_Number>_<Markdown_Title>.md
| | | ├── .....
```
**File Naming convention** AGL follows Snake Case (snake_case) naming convention to name the documentation files.
This type of naming combines words simply by replacing the space with an underscore (_).
All the names will also include a index number before the name.
Index number will use two digit numbers from 01-99 followed by name of the file.
For example: If the file name is Build Process then it will be written as 01_build_process.md
**Note:** If a file needs to be inserted in between already created sequences, then the index number will be the last index number followed by new numbering. For example, A new file is inserted between 06-07, then the index number for the new file will be 07_01, as in gist sorting, 07_01 will appear after 06 and before 07.
## Markdown Formatting
1. Add following at the start of each markdown :
```sh
---
title: <enter-title>
---
```
2. Internal Linking :
```sh
[<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)
```
## Test Hyperlinks
[Broken Link Checker](https://github.com/stevenvachon/broken-link-checker) is a tool that allows to
check all the hyperlinks in the site.
For testing hyperlinks as soon as the local site is running, do:
```sh
$ blc http://localhost:8000 -ro
```
For testing hyperlinks of live website do:
```sh
$ blc https://docs.automotivelinux.org/en/master/ -ro
```
The ```Broken Link Checker``` output will display the broken link and there location in
the site.
## Submitting changes
1. Install Git Review
```sh
#recent version of git-review (>=1.28.0 is required)
$ sudo pip3 install git-review
```
2. Write commit message (**Note:** Please follow [submitting changes](./04_Submitting_Changes.md) guideline to write your commit message.)
```sh
# track all the new changes
$ git add .
# Write the commit message
$ git commit --signoff
```
3. Push changes for review to Gerrit
```sh
# first time only
$ git review -s
# then to push use
$ git review
```
|
