docs/07_How_To_Contribute/08_Adding_Documentation.md

   1 ---
   2 title: Adding Documentation
   3 ---
   4
   5 The [documentation gerrit
   6 repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation)
   7 contains AGL documentation website template and content, rendering is visible at
   8 [https://docs.automotivelinux.org](https://docs.automotivelinux.org).
   9 The documentation site is hosted on
  10 [readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and
  11 corresponding builds are mentioned
  12 [here](https://readthedocs.org/projects/automotivegradelinux/builds/).
  13
  14 ## Download Repository
  15
  16
  17 Clone with commit-msg hook :
  18
  19 ```sh
  20 $ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 <LFID>@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/"
  21 ```
  22
  23 ## Building a local site
  24
  25 1. Change into the directory
  26
  27     ```sh
  28     $ cd documentation
  29     ```
  30
  31 2. Install MkDocs and rtd-dropdown theme
  32
  33     ```sh
  34     $ sudo pip install -r requirements.txt
  35     ```
  36
  37 3. If pip is not already installed then install it
  38     ```sh
  39     $ sudo apt-install python3-pip
  40     ```
  41
  42
  43 4. Serve locally (default rendered at [127.0.0.1:8000/](127.0.0.1:8000/)):
  44
  45     ```sh
  46     $ sudo mkdocs serve
  47     ```
  48
  49 Process to **add new or edit existing** markdown files to AGL documentation:
  50
  51 ## Directory Structure
  52
  53 Find existing or add new markdowns in the following directory structure.
  54
  55 ```sh
  56 documentation
  57 ├── docs
  58 │   ├── 1_Getting_Started
  59 │   │   ├── 1_Quickstart
  60 │   │   └── 2_Building_AGL_Image
  61 |   ├── .....
  62 |   |
  63 |   ├──<Chapter_Number>_<Chapter_Name>
  64 |   |   ├──<Subchapter_Number>_<Subchapter_Name>
  65 |   |   |   ├──<Index_Number>_<Markdown_Title>.md
  66 |   |   |   ├── .....
  67 ```
  68 **File Naming convention** AGL follows Snake Case (snake_case) naming convention to name the documentation files.
  69 This type of naming combines words simply by replacing the space with an underscore (_).
  70 All the names will also include a index number before the name.
  71 Index number will use two digit numbers from 01-99 followed by name of the file.
  72 For example: If the file name is Build Process then it will be written as 01_build_process.md
  73
  74 **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.
  75
  76 ## Markdown Formatting
  77
  78   1. Add following at the start of each markdown :
  79
  80     ```sh
  81     ---
  82     title: <enter-title>
  83     ---
  84     ```
  85
  86   2. Internal Linking :
  87
  88     ```sh
  89     [<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)
  90
  91
  92
  93     ```
  94
  95 ## Test Hyperlinks
  96 [Broken Link Checker](https://github.com/stevenvachon/broken-link-checker) is a tool that allows to
  97 check all the hyperlinks in the site.
  98
  99 For testing hyperlinks as soon as the local site is running, do:
 100
 101 ```sh
 102 $ blc http://localhost:8000 -ro
 103 ```
 104
 105
 106 For testing hyperlinks of live website do:
 107
 108 ```sh
 109 $ blc https://docs.automotivelinux.org/en/master/ -ro
 110 ```
 111
 112 The ```Broken Link Checker``` output will display the broken link and there location in
 113 the site.
 114
 115
 116 ## Submitting changes
 117
 118 1. Install Git Review
 119
 120     ```sh
 121     #recent version of git-review  (>=1.28.0 is required)
 122     $ sudo pip3 install git-review
 123     ```
 124
 125 2. Write commit message (**Note:** Please follow [submitting changes](./04_Submitting_Changes.md) guideline to write your commit message.)
 126
 127     ```sh
 128     # track all the new changes
 129     $ git add .
 130
 131     # Write the commit message
 132     $ git commit --signoff
 133     ```
 134
 135 3. Push changes for review to Gerrit
 136
 137     ```sh
 138     # first time only
 139     $ git review -s
 140
 141     # then to push use
 142     $ git review
 143     ```