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     $ pip install -r requirements.txt
  35     ```
  36
  37    Missing packages will be installed for the current user, in particular,
  38    scripts will be installed to `$HOME/.local/bin`. Ensure `$HOME/.local/bin` is
  39    in your `PATH` to be able to run `mkdocs` command.
  40
  41 3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)):
  42
  43     ```sh
  44     $ mkdocs serve
  45     ```
  46
  47 Process to **add new or edit existing** markdown files to AGL documentation:
  48
  49 ## Directory Structure
  50
  51 Find existing or add new markdowns in the following directory structure.
  52
  53 ```sh
  54 documentation
  55 ├── docs
  56 │   ├── 0_Getting_Started
  57 │   │   ├── 1_Quickstart
  58 │   │   └── 2_Building_AGL_Image
  59 |   ├── .....
  60 |   |
  61 |   ├──<Chapter-Number>_<Chapter-Name>
  62 |   |   ├──<Subchapter-Number>_<Subchapter-Name>
  63 |   |   |   ├──<Index-Number>_<Markdown-Title>.md
  64 |   |   |   ├── .....
  65 ```
  66
  67 ## Markdown Formatting
  68
  69   1. Add following at the start of each markdown :
  70
  71     ```sh
  72     ---
  73     title: <enter-title>
  74     ---
  75     ```
  76
  77   2. Internal Linking :
  78
  79     ```sh
  80     [<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)
  81     ```
  82
  83 ## Test Hyperlinks
  84
  85 [LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to
  86 check all the hyperlinks in the site.
  87
  88 For testing hyperlinks as soon as the local site is running, do:
  89
  90 ```sh
  91 linkchecker http://localhost:8000
  92 ```
  93
  94 The ```linkchecker``` output will display the broken link and there location in
  95 the site.
  96
  97
  98 ## Submitting changes
  99
 100 1. Install Git Review
 101
 102     ```sh
 103     #recent version of git-review  (>=1.28.0 is required)
 104     sudo pip3 install git-review
 105     ```
 106
 107 2. Write commit message
 108
 109     ```sh
 110     # track all the new changes
 111     git add .
 112
 113     # Write the commit message
 114     git commit --signoff
 115     ```
 116
 117 3. Push changes for review to Gerrit
 118
 119     ```sh
 120     # first time only
 121     git review -s
 122
 123     # then to push use
 124     git review
 125     ```
 126