diff options
author | Jan-Simon Moeller <jsmoeller@linuxfoundation.org> | 2021-01-14 18:18:25 +0100 |
---|---|---|
committer | Jan-Simon Moeller <jsmoeller@linuxfoundation.org> | 2021-01-20 23:52:26 +0000 |
commit | f81a7f42d8f10467108bab784117a380e0070ece (patch) | |
tree | 28f7c7a31cc279f176508cc4eb0f9dc3b3e2acbe /docs/6_How_To_Contribute/8_Adding_Documentation.md | |
parent | 48873cd821ac1cd50bf33a737a898f4c58702a62 (diff) |
Add a category for agl-compositor and rba documentation
Create a home for docs of compositor, rba and pipewire/wireplumber.
Also add a .gitignore file.
Signed-off-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
Change-Id: Id1f9812d0f4db83cb72bf03987dc95d754e00725
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/25913
Diffstat (limited to 'docs/6_How_To_Contribute/8_Adding_Documentation.md')
-rw-r--r-- | docs/6_How_To_Contribute/8_Adding_Documentation.md | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/docs/6_How_To_Contribute/8_Adding_Documentation.md b/docs/6_How_To_Contribute/8_Adding_Documentation.md new file mode 100644 index 0000000..d2aad82 --- /dev/null +++ b/docs/6_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 + + ```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 |