Updating File name and links in the documentation

[AGL/documentation.git] / docs / 07_How_To_Contribute / 08_Adding_Documentation.md

diff --git a/docs/07_How_To_Contribute/08_Adding_Documentation.md b/docs/07_How_To_Contribute/08_Adding_Documentation.md
new file mode 100644 (file)
index 0000000..a54058d
--- /dev/null
+++ b/docs/07_How_To_Contribute/08_Adding_Documentation.md
@@ -0,0 +1,131 @@
+---
+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 (default 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
+│   ├── 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
+
+  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 (**Note:** Please follow [submitting changes](./04_Submitting_Changes.md) guideline to write your 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
+    ```