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://automotivegradelinux.readthedocs.io/en/latest/](https://automotivegradelinux.readthedocs.io/en/latest/).
   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. Serve locally (default rendered at [127.0.0.1:8000/](127.0.0.1:8000/)):
  38
  39     ```sh
  40     $ sudo mkdocs serve
  41     ```
  42
  43 Process to **add new or edit existing** markdown files to AGL documentation:
  44
  45 ## Directory Structure
  46
  47 Find existing or add new markdowns in the following directory structure.
  48
  49 ```sh
  50 documentation
  51 ├── docs
  52 │   ├── 1_Getting_Started
  53 │   │   ├── 1_Quickstart
  54 │   │   └── 2_Building_AGL_Image
  55 |   ├── .....
  56 |   |
  57 |   ├──<Chapter_Number>_<Chapter_Name>
  58 |   |   ├──<Subchapter_Number>_<Subchapter_Name>
  59 |   |   |   ├──<Index_Number>_<Markdown_Title>.md
  60 |   |   |   ├── .....
  61 ```
  62 **File Naming convention** AGL follows Snake Case (snake_case) naming convention to name the documentation files.
  63 This type of naming combines words simply by replacing the space with an underscore (_).
  64 All the names will also include a index number before the name.
  65 Index number will use two digit numbers from 01-99 followed by name of the file.
  66 For example: If the file name is Build Process then it will be written as 01_build_process.md
  67
  68 **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.
  69
  70 ## Markdown Formatting
  71
  72   1. Add following at the start of each markdown :
  73
  74     ```sh
  75     ---
  76     title: <enter-title>
  77     ---
  78     ```
  79
  80   2. Internal Linking :
  81
  82     ```sh
  83     [<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)
  84
  85
  86
  87     ```
  88
  89 ## Test Hyperlinks
  90 [Broken Link Checker](https://github.com/stevenvachon/broken-link-checker) is a tool that allows to
  91 check all the hyperlinks in the site.
  92
  93 For testing hyperlinks as soon as the local site is running, do:
  94
  95 ```sh
  96 $ blc http://localhost:8000 -ro
  97 ```
  98
  99
 100 For testing hyperlinks of live website do:
 101
 102 ```sh
 103 $ blc https://docs.automotivelinux.org/en/master/ -ro
 104 ```
 105
 106 The ```Broken Link Checker``` output will display the broken link and there location in
 107 the site.
 108
 109
 110 ## Submitting changes
 111
 112 1. Install Git Review
 113
 114     ```sh
 115     #recent version of git-review  (>=1.28.0 is required)
 116     $ sudo pip3 install git-review
 117     ```
 118
 119 2. Write commit message (**Note:** Please follow [submitting changes](./04_Submitting_Changes.md) guideline to write your commit message.)
 120
 121     ```sh
 122     # track all the new changes
 123     $ git add .
 124
 125     # Write the commit message
 126     $ git commit --signoff
 127     ```
 128
 129 3. Push changes for review to Gerrit
 130
 131     ```sh
 132     # first time only
 133     $ git review -s
 134
 135     # then to push use
 136     $ git review
 137     ```