docs/5_How_To/2_Usage.md

   1 ---
   2 edit_link: ''
   3 title: Usage
   4 origin_url: >-
   5   https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/handle-docs/documentation-usage.md
   6 ---
   7
   8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/howto/master/howto-add-docs-handle-docs-book.yml -->
   9
  10 # Documentation Usage
  11
  12 The [docs-webtemplate](https://github.com/automotive-grade-linux/docs-webtemplate)
  13 repository contains AGL documentation website template, rendering is visible at
  14 <https://docs.automotivelinux.org.>
  15 This website relies on the generator located in
  16 [docs-tools](https://github.com/automotive-grade-linux/docs-tools).
  17
  18 ## Download Sources
  19
  20 Get the ```setupdocs.sh``` script to initialize your environment.
  21
  22 ```bash
  23 wget https://raw.githubusercontent.com/automotive-grade-linux/docs-webtemplate/master/setupdocs.sh
  24 ```
  25
  26 This script fetches [docs-tools](https://github.com/automotive-grade-linux/docs-tools), install npm modules.
  27
  28 ```bash
  29 mkdir docs-webtemplate
  30 bash setupdocs.sh --directory=docs-webtemplate
  31 ```
  32
  33 For consulting help, do:
  34
  35 ```bash
  36 bash setupdocs.sh --help
  37 ```
  38
  39 ## Building a local site
  40
  41 In docs-webtemplate directory:
  42
  43 ```bash
  44 make serve
  45 ```
  46
  47 For cleaning your work, use:
  48
  49 ```bash
  50 make clean
  51 ```
  52
  53 ## Documentation from local repositories
  54
  55 It is also possible to use markdown files from local repositories.
  56
  57 For local fetch, a specific file named  ```__fetched_files_local.yml```
  58 was introduced.
  59
  60 This file is used to overload ```url_fetch``` in section_<version>.yml
  61 in order to use local repositories on not remote ones.
  62
  63 Thus, this file is needed to be added in the docs-webtemplate root,
  64 see an example below:
  65
  66 ```bash
  67 ############__fetched_files_local.yml##############
  68 -
  69     url_fetch : <pathToDocsSources>/docs-sources/
  70     git_name   : automotive-grade-linux/docs-sources
  71 -
  72     url_fetch : <pathToXdsDocs>/xds-docs/
  73     git_name   : src/xds/xds-docs
  74 -
  75     git_name: AGL/meta-renesas-rcar-gen3
  76     url_fetch: <pathToMetaRenesas>/meta-renesas-rcar-gen3
  77 ###################################################
  78 ```
  79
  80 It is also possible to use ```id``` instead of ```git_name```.
  81
  82 ## Test Hyperlinks
  83
  84 [LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to check all the hyperlinks in the site.
  85
  86 For testing hyperlinks as soon as the local site is running, do:
  87
  88 ```bash
  89 make linkchecker
  90 ```
  91
  92 or
  93
  94 ```bash
  95 linkchecker http://localhost:4000
  96 ```
  97
  98 The ```linkchecker``` output will display the broken link and there location
  99 in the site.