2 title: Adding Documentation
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/).
14 ## Download Repository
17 Clone with commit-msg hook :
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/"
23 ## Building a local site
25 1. Change into the directory
31 2. Install MkDocs and rtd-dropdown theme
34 $ sudo pip install -r requirements.txt
37 3. If pip is not already installed then install it
39 $ sudo apt-install python3-pip
43 4. Serve locally (default rendered at [127.0.0.1:8000/](127.0.0.1:8000/)):
49 Process to **add new or edit existing** markdown files to AGL documentation:
51 ## Directory Structure
53 Find existing or add new markdowns in the following directory structure.
58 │ ├── 1_Getting_Started
60 │ │ └── 2_Building_AGL_Image
63 | ├──<Chapter_Number>_<Chapter_Name>
64 | | ├──<Subchapter_Number>_<Subchapter_Name>
65 | | | ├──<Index_Number>_<Markdown_Title>.md
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
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.
76 ## Markdown Formatting
78 1. Add following at the start of each markdown :
89 [<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)
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.
99 For testing hyperlinks as soon as the local site is running, do:
102 $ blc http://localhost:8000 -ro
106 For testing hyperlinks of live website do:
109 $ blc https://docs.automotivelinux.org/en/master/ -ro
112 The ```Broken Link Checker``` output will display the broken link and there location in
116 ## Submitting changes
118 1. Install Git Review
121 #recent version of git-review (>=1.28.0 is required)
122 $ sudo pip3 install git-review
125 2. Write commit message (**Note:** Please follow [submitting changes](./04_Submitting_Changes.md) guideline to write your commit message.)
128 # track all the new changes
131 # Write the commit message
132 $ git commit --signoff
135 3. Push changes for review to Gerrit