Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: growupboron <shankhoghosh123@gmail.com>
- Loading branch information
1 parent
f1f4612
commit aadaefc
Showing
5 changed files
with
121 additions
and
140 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
114 changes: 114 additions & 0 deletions
114
docs/5_How_To_Contribute/1_How_to_add_documentation_to_AGL.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,114 @@ | ||
--- | ||
edit_link: '' | ||
title: Adding Documentation | ||
origin_url: > | ||
--- | ||
|
||
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 | ||
|
||
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 | ||
| ├── ..... | ||
| | | ||
| ├──<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 | ||
``` |
This file was deleted.
Oops, something went wrong.
72 changes: 0 additions & 72 deletions
72
docs/5_How_To_Contribute/2_How_to_add_documentation_to_AGL.md
This file was deleted.
Oops, something went wrong.
Binary file not shown.