summaryrefslogtreecommitdiffstats
path: root/docs/5_How_To_Contribute/8_Adding_Documentation.md
blob: d2aad82d74a8666df4cd98928d8c53a631047a8c (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
---
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://automotivegradelinux.readthedocs.io/en/latest/](https://automotivegradelinux.readthedocs.io/en/latest/).
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. Serve locally (defaultly 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
│   ├── 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
    ```