README.md

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