README.md

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