Adding Documentation - AGL Documentation

The documentation gerrit repository contains AGL documentation website template and content, rendering is visible at https://docs.automotivelinux.org. The documentation site is hosted on readthedocs and corresponding builds are mentioned here.

Download Repository¶

Clone with commit-msg hook :

$ 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¶

Change into the directory
```
$ cd documentation
```
Install MkDocs and rtd-dropdown theme
```
$ sudo pip install -r requirements.txt
```
If pip is not already installed then install it
```
$ sudo apt-install python3-pip
```
Serve locally (default rendered at 127.0.0.1:8000/):
```
$ 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.

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¶

Add following at the start of each markdown :
```
---
title: <enter-title>
---
```

Internal Linking :

[<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)

Test Hyperlinks¶

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:

$ blc http://localhost:8000 -ro

For testing hyperlinks of live website do:

$ 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¶

Install Git Review

#recent version of git-review  (>=1.28.0 is required)
$ sudo pip3 install git-review

Write commit message (Note: Please follow submitting changes guideline to write your commit message.)

# track all the new changes
$ git add .

# Write the commit message
$ git commit --signoff

Push changes for review to Gerrit

# first time only
$ git review -s

# then to push use
$ git review