diff options
Diffstat (limited to 'docs/7_How_To_Contribute/8_Adding_Documentation.md')
-rw-r--r-- | docs/7_How_To_Contribute/8_Adding_Documentation.md | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/docs/7_How_To_Contribute/8_Adding_Documentation.md b/docs/7_How_To_Contribute/8_Adding_Documentation.md new file mode 100644 index 0000000..7797ab5 --- /dev/null +++ b/docs/7_How_To_Contribute/8_Adding_Documentation.md @@ -0,0 +1,121 @@ +--- +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://automotivegradelinux.readthedocs.io/en/latest/](https://automotivegradelinux.readthedocs.io/en/latest/). +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 + + +Clone with commit-msg hook : + +```sh +$ 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 + +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 +| ├── ..... +| | +| ├──<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 (**Note:** Please follow [submitting changes](./4_Submitting_Changes.md) guideline to write your 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 + ``` |