# agl-docs (master) Revamping and restructuring Automotive Grade Linux's documentation site under GSoD'20. 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.automotivelinux.org/en/master/](hhttps://docs.automotivelinux.org/en/master/). The documentation site is hosted on [readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and corresponding builds are mentioned [here](https://readthedocs.org/projects/automotivegradelinux/builds/). ## Download Repository Kindly check [this](https://wiki.automotivelinux.org/agl-distro/contributing) and clone with commit-msg hook : ```sh $ git clone "ssh://$USER@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 $USER@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" ``` ## Building a local site 1. Change into the directory ```sh $ cd documentation ``` 2. Install MkDocs and rtd-dropdown theme ```sh $ pip install -r requirements.txt ``` Missing packages will be installed for the current user, in particular, scripts will be installed to `$HOME/.local/bin`. Ensure `$HOME/.local/bin` is in your `PATH` to be able to run `mkdocs` command. 3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)): ```sh $ 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. ```sh 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 1. Add following at the start of each markdown : ```sh --- title: <enter-title> --- ``` 2. Internal Linking : ```sh [<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md) ``` ## Test Hyperlinks [LinkChecker](https://wummel.github.io/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: ```sh linkchecker http://localhost:8000 ``` The ```linkchecker``` output will display the broken link and there location in the site. ## Submitting changes 1. Install Git Review ```sh #recent version of git-review (>=1.28.0 is required) sudo pip3 install git-review ``` 2. Write commit message ```sh # track all the new changes git add . # Write the commit message git commit --signoff ``` 3. Push changes for review to Gerrit ```sh # first time only git review -s # then to push use git review ```