diff options
author | 2022-11-07 16:18:44 -0600 | |
---|---|---|
committer | 2022-11-08 14:47:43 +0000 | |
commit | 8be9db6f309e1e1b547e187c5db6ceac15f85a50 (patch) | |
tree | ca3a6179b37b381eaee1bf948aebf78c809883b4 /docs/7_How_To_Contribute/8_Adding_Documentation.md | |
parent | e660399f8b909146a699e44eb340b8c0b7e7f12f (diff) |
Fixing the index numbering
Fixing the index numbering for all documentation
Bug-AGL: [SPEC-4470]
Signed-off-by: Vinod Ahuja <vahuja@unomaha.edu>
Change-Id: I96b482a3ab598f0739c692e301de66c0553ba0e4
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/28118
Reviewed-by: Walt Miner <wminer@linuxfoundation.org>
Reviewed-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
Tested-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
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 + ``` |