README.md

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