blob: 66e22b2821bf095be72f1659207e69c3234bfc02 (
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
|
# agl-docs (needlefish)
Revamping and restructuring Automotive Grade Linux's documentation site under
GSoD'20.
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/en/needlefish/](hhttps://docs.automotivelinux.org/en/needlefish/).
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
Kindly check [this](https://wiki.automotivelinux.org/agl-distro/contributing)
and clone with commit-msg hook :
```sh
$ git clone "ssh://$USER@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 $USER@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
$ pip install -r requirements.txt
```
Missing packages will be installed for the current user, in particular,
scripts will be installed to `$HOME/.local/bin`. Ensure `$HOME/.local/bin` is
in your `PATH` to be able to run `mkdocs` command.
3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)):
```sh
$ 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
│ ├── 0_Getting_Started
│ │ ├── 1_Quickstart
│ │ └── 2_Building_AGL_Image
| ├── .....
| |
| ├──<Chapter-Number>_<Chapter-Name>
| | ├──<Subchapter-Number>_<Subchapter-Name>
| | | ├──<Index-Number>_<Markdown-Title>.md
| | | ├── .....
```
## 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
[LinkChecker](https://wummel.github.io/linkchecker/) 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
linkchecker http://localhost:8000
```
The ```linkchecker``` 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
```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
```
|
