agl-docs (master)

Revamping and restructuring Automotive Grade Linux's documentation site under GSoD'20.

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

Download Repository

Kindly check this and clone with commit-msg hook :

$ 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

   $ cd documentation

2. Install MkDocs and rtd-dropdown theme

   $ 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/):

   $ 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
│   ├── 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 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:

linkchecker http://localhost:8000

The linkchecker output will display the broken link and there location in the site.

Submitting changes

1. Install Git Review

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

2. Write commit message

   # track all the new changes
   git add .
   
   # Write the commit message
   git commit --signoff

3. Push changes for review to Gerrit

   # first time only
   git review -s
   
   # then to push use
   git review