From eefc3ab6cbb8a5901632f46d99e13c8d90b2415d Mon Sep 17 00:00:00 2001 From: growupboron Date: Fri, 9 Oct 2020 00:19:18 +0530 Subject: rewrote quickstart, build-process Revamped and updated documentation to install and build AGL images. (removed whitespaces, added contribution guide, corrected rcar-gen3 section 7, added aglsetup.h flags to hardware support, some minor changes) Bug-AGL: [SPEC-3633] Signed-off-by: Shankho Boron Ghosh Change-Id: Iedb6c7dc1661f4bc58b5f25ea5d188778c7ff908 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/25407 Reviewed-by: Jan-Simon Moeller Tested-by: Jan-Simon Moeller --- .../1_How_to_add_documentation_to_AGL.md | 113 +++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/5_How_To_Contribute/1_How_to_add_documentation_to_AGL.md (limited to 'docs/5_How_To_Contribute') diff --git a/docs/5_How_To_Contribute/1_How_to_add_documentation_to_AGL.md b/docs/5_How_To_Contribute/1_How_to_add_documentation_to_AGL.md new file mode 100644 index 0000000..ed7eb6d --- /dev/null +++ b/docs/5_How_To_Contribute/1_How_to_add_documentation_to_AGL.md @@ -0,0 +1,113 @@ +--- +title: Adding Documentation +--- + +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/). + +## 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 + $ sudo pip install -r requirements.txt + ``` + +3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)): + + ```sh + $ 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. + +```sh +documentation +├── docs +│   ├── 0_Getting_Started +│   │   ├── 1_Quickstart +│   │   └── 2_Building_AGL_Image +| ├── ..... +| | +| ├──_ +| | ├──_ +| | | ├──_.md +| | | ├── ..... +``` + +## Markdown Formatting + + 1. Add following at the start of each markdown : + + ```sh + --- + title: + --- + ``` + + 2. Internal Linking : + + ```sh + [](../_/_/_.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 + ``` \ No newline at end of file -- cgit