docs/5_How_To_Contribute/1_How_to_add_documentation_to_AGL.md

   1 ---
   2 title: Adding Documentation
   3 ---
   4
   5 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/).
   6
   7 ## Download Repository
   8
   9
  10 Kindly check [this](https://wiki.automotivelinux.org/agl-distro/contributing) and clone with commit-msg hook :
  11
  12 ```sh
  13 $ git clone "ssh://$USER@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 $USER@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/"
  14 ```
  15
  16 ## Building a local site
  17
  18 1. Change into the directory
  19
  20     ```sh
  21     $ cd documentation
  22     ```
  23
  24 2. Install MkDocs and rtd-dropdown theme
  25
  26     ```sh
  27     $ sudo pip install -r requirements.txt
  28     ```
  29
  30 3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)):
  31
  32     ```sh
  33     $ sudo mkdocs serve
  34     ```
  35
  36 Process to **add new or edit existing** markdown files to AGL documentation:
  37
  38 ## Directory Structure
  39
  40 Find existing or add new markdowns in the following directory structure.
  41
  42 ```sh
  43 documentation
  44 ├── docs
  45 │   ├── 0_Getting_Started
  46 │   │   ├── 1_Quickstart
  47 │   │   └── 2_Building_AGL_Image
  48 |   ├── .....
  49 |   |
  50 |   ├──<Chapter-Number>_<Chapter-Name>
  51 |   |   ├──<Subchapter-Number>_<Subchapter-Name>
  52 |   |   |   ├──<Index-Number>_<Markdown-Title>.md
  53 |   |   |   ├── .....
  54 ```
  55
  56 ## Markdown Formatting
  57
  58   1. Add following at the start of each markdown :
  59
  60     ```sh
  61     ---
  62     title: <enter-title>
  63     ---
  64     ```
  65
  66   2. Internal Linking :
  67
  68     ```sh
  69     [<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)
  70     ```
  71
  72 ## Test Hyperlinks
  73
  74 [LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to check all the hyperlinks in the site.
  75
  76 For testing hyperlinks as soon as the local site is running, do:
  77
  78 ```sh
  79 linkchecker http://localhost:8000
  80 ```
  81
  82 The ```linkchecker``` output will display the broken link and there location
  83 in the site.
  84
  85
  86 ## Submitting changes
  87
  88 1. Install Git Review
  89
  90     ```sh
  91     #recent version of git-review  (>=1.28.0 is required)
  92     sudo pip3 install git-review
  93     ```
  94
  95 2. Write commit message
  96
  97     ```sh
  98     # track all the new changes
  99     git add .
 100
 101     # Write the commit message
 102     git commit --signoff
 103     ```
 104
 105 3. Push changes for review to Gerrit
 106
 107     ```sh
 108     # first time only
 109     git review -s
 110
 111     # then to push use
 112     git review
 113     ```