README.md

   1 # agl-docs (master)
   2 Revamping and restructuring Automotive Grade Linux's documentation site under GSoD'20.
   3
   4 -> [The working documentation site.](https://docs-agl.readthedocs.io)
   5
   6 -> [ReadTheDocs project page.](https://readthedocs.org/projects/docs-agl/)
   7
   8 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/).
   9
  10 ## Download Repository
  11
  12 Kindly check [this](https://wiki.automotivelinux.org/agl-distro/contributing) and clone with commit-msg hook :
  13
  14 ```sh
  15 $ git clone "ssh://$USER@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 $USER@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/"
  16 ```
  17
  18 ## Building a local site
  19
  20 1. Change into the directory
  21
  22     ```sh
  23     $ cd documentation
  24     ```
  25
  26 2. Install MkDocs and rtd-dropdown theme
  27
  28     ```sh
  29     $ sudo pip install -r requirements.txt
  30     ```
  31
  32 3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)):
  33
  34     ```sh
  35     $ sudo mkdocs serve
  36     ```
  37
  38 Process to **add new or edit existing** markdown files to AGL documentation:
  39
  40 ## Directory Structure
  41
  42 Find existing or add new markdowns in the following directory structure.
  43
  44 ```sh
  45 documentation
  46 ├── docs
  47 │   ├── 0_Getting_Started
  48 │   │   ├── 1_Quickstart
  49 │   │   └── 2_Building_AGL_Image
  50 |   ├── .....
  51 |   |
  52 |   ├──<Chapter-Number>_<Chapter-Name>
  53 |   |   ├──<Subchapter-Number>_<Subchapter-Name>
  54 |   |   |   ├──<Index-Number>_<Markdown-Title>.md
  55 |   |   |   ├── .....
  56 ```
  57
  58 ## Markdown Formatting
  59
  60   1. Add following at the start of each markdown :
  61
  62     ```sh
  63     ---
  64     title: <enter-title>
  65     ---
  66     ```
  67
  68   2. Internal Linking :
  69
  70     ```sh
  71     [<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)
  72     ```
  73
  74 ## Test Hyperlinks
  75
  76 [LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to check all the hyperlinks in the site.
  77
  78 For testing hyperlinks as soon as the local site is running, do:
  79
  80 ```sh
  81 linkchecker http://localhost:8000
  82 ```
  83
  84 The ```linkchecker``` output will display the broken link and there location
  85 in the site.
  86
  87
  88 ## Submitting changes
  89
  90 1. Install Git Review
  91
  92     ```sh
  93     #recent version of git-review  (>=1.28.0 is required)
  94     sudo pip3 install git-review
  95     ```
  96
  97 2. Write commit message
  98
  99     ```sh
 100     # track all the new changes
 101     git add .
 102
 103     # Write the commit message
 104     git commit --signoff
 105     ```
 106
 107 3. Push changes for review to Gerrit
 108
 109     ```sh
 110     # first time only
 111     git review -s
 112
 113     # then to push use
 114     git review
 115     ```
 116