1 # agl-docs (needlefish)
2 Revamping and restructuring Automotive Grade Linux's documentation site under
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/en/needlefish/](hhttps://docs.automotivelinux.org/en/needlefish/).
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
16 Kindly check [this](https://wiki.automotivelinux.org/agl-distro/contributing)
17 and clone with commit-msg hook :
20 $ git clone "ssh://$USER@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 $USER@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 $ pip install -r requirements.txt
37 Missing packages will be installed for the current user, in particular,
38 scripts will be installed to `$HOME/.local/bin`. Ensure `$HOME/.local/bin` is
39 in your `PATH` to be able to run `mkdocs` command.
41 3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)):
47 Process to **add new or edit existing** markdown files to AGL documentation:
49 ## Directory Structure
51 Find existing or add new markdowns in the following directory structure.
56 │ ├── 0_Getting_Started
58 │ │ └── 2_Building_AGL_Image
61 | ├──<Chapter-Number>_<Chapter-Name>
62 | | ├──<Subchapter-Number>_<Subchapter-Name>
63 | | | ├──<Index-Number>_<Markdown-Title>.md
67 ## Markdown Formatting
69 1. Add following at the start of each markdown :
80 [<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)
85 [LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to
86 check all the hyperlinks in the site.
88 For testing hyperlinks as soon as the local site is running, do:
91 linkchecker http://localhost:8000
94 The ```linkchecker``` output will display the broken link and there location in
100 1. Install Git Review
103 #recent version of git-review (>=1.28.0 is required)
104 sudo pip3 install git-review
107 2. Write commit message
110 # track all the new changes
113 # Write the commit message
117 3. Push changes for review to Gerrit