README.md

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