rewrote quickstart, build-process

Revamped and updated documentation to install and build AGL images.
(removed whitespaces, added contribution guide, corrected rcar-gen3 section 7, added aglsetup.h flags to hardware support, some minor changes)

Bug-AGL: [SPEC-3633]

Signed-off-by: Shankho Boron Ghosh <shankhoghosh123@gmail.com>
Change-Id: Iedb6c7dc1661f4bc58b5f25ea5d188778c7ff908
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/25407
Reviewed-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
Tested-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>

1 files changed, 105 insertions, 7 deletions

diff --git a/README.md b/README.md
index 803cfcb..045add8 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,116 @@
 # agl-docs (master)
 Revamping and restructuring Automotive Grade Linux's documentation site under GSoD'20.
 
--> [The working documentation site.](https://agl-docs.readthedocs.io)
+-> [The working documentation site.](https://docs-agl.readthedocs.io)
 
--> [ReadTheDocs project page.](https://readthedocs.org/projects/agl-docs/)
+-> [ReadTheDocs project page.](https://readthedocs.org/projects/docs-agl/)
 
-## To setup local build environment :
+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-agl.readthedocs.io/en/latest/](https://docs-agl.readthedocs.io/en/latest/). The documentation site is hosted on [readthedocs](https://readthedocs.org/projects/docs-agl/) and corresponding builds are mentioned [here](https://readthedocs.org/projects/docs-agl/builds/).
 
-1) Clone this Repository : ```git clone https://github.com/growupboron/agl-docs.git```
+## Download Repository
 
-2) Change into the directory : ```cd agl-docs/```
+Kindly check [this](https://wiki.automotivelinux.org/agl-distro/contributing) and clone with commit-msg hook :
 
-3) Install MkDocs and rtd-dropdown theme : ```sudo pip3 install -r requirements.txt```
+```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/"
+```
 
-4) Serve it, it would get defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/) : ```sudo mkdocs serve```
+## 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
+    ```