The documentation gerrit repository contains AGL documentation website template and content, rendering is visible at https://automotivegradelinux.readthedocs.io/en/latest/. The documentation site is hosted on readthedocs and corresponding builds are mentioned here.
Download Repository
Clone with commit-msg hook :
$ 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
-
Change into the directory
$ cd documentation -
Install MkDocs and rtd-dropdown theme
$ sudo pip install -r requirements.txt -
Serve locally (defaultly rendered at 127.0.0.1:8000/):
$ 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.
documentation
├── docs
│ ├── 0_Getting_Started
│ │ ├── 1_Quickstart
│ │ └── 2_Building_AGL_Image
| ├── .....
| |
| ├──<Chapter-Number>_<Chapter-Name>
| | ├──<Subchapter-Number>_<Subchapter-Name>
| | | ├──<Index-Number>_<Markdown-Title>.md
| | | ├── .....
Markdown Formatting
-
Add following at the start of each markdown :
--- title: <enter-title> --- -
Internal Linking :
[<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)
Test Hyperlinks
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:
$ linkchecker http://localhost:8000
The linkchecker output will display the broken link and there location in
the site.
Submitting changes
-
Install Git Review
#recent version of git-review (>=1.28.0 is required) $ sudo pip3 install git-review -
Write commit message
# track all the new changes $ git add . # Write the commit message $ git commit --signoff -
Push changes for review to Gerrit
# first time only $ git review -s # then to push use $ git review