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