X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=README.md;h=a14fcf644928705f2dbfca484bb2282e0d00b399;hb=refs%2Fheads%2Fmaster;hp=803cfcbe5cc06b1ffd67077dedb0c56b23051b10;hpb=4aad369c9728061c97b3de792286e743ee884b09;p=AGL%2Fdocumentation.git diff --git a/README.md b/README.md index 803cfcb..a14fcf6 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,126 @@ # agl-docs (master) -Revamping and restructuring Automotive Grade Linux's documentation site under GSoD'20. +Revamping and restructuring Automotive Grade Linux's documentation site under +GSoD'20. --> [The working documentation site.](https://agl-docs.readthedocs.io) +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.automotivelinux.org/en/master/](hhttps://docs.automotivelinux.org/en/master/). +The documentation site is hosted on +[readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and +corresponding builds are mentioned +[here](https://readthedocs.org/projects/automotivegradelinux/builds/). --> [ReadTheDocs project page.](https://readthedocs.org/projects/agl-docs/) +## Download Repository -## To setup local build environment : +Kindly check [this](https://wiki.automotivelinux.org/agl-distro/contributing) +and clone with commit-msg hook : -1) Clone this Repository : ```git clone https://github.com/growupboron/agl-docs.git``` +```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/" +``` -2) Change into the directory : ```cd agl-docs/``` +## Building a local site -3) Install MkDocs and rtd-dropdown theme : ```sudo pip3 install -r requirements.txt``` +1. Change into the directory -4) Serve it, it would get defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/) : ```sudo mkdocs serve``` + ```sh + $ cd documentation + ``` +2. Install MkDocs and rtd-dropdown theme + + ```sh + $ pip install -r requirements.txt + ``` + + Missing packages will be installed for the current user, in particular, + scripts will be installed to `$HOME/.local/bin`. Ensure `$HOME/.local/bin` is + in your `PATH` to be able to run `mkdocs` command. + +3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)): + + ```sh + $ 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 + ```