summaryrefslogtreecommitdiffstats
path: root/docs/handle-docs
diff options
context:
space:
mode:
authorClément Bénier <clement.benier@iot.bzh>2019-04-16 18:40:29 +0200
committerClément Bénier <clement.benier@iot.bzh>2019-04-16 18:42:37 +0200
commit68de85c25c1d90598c5d2a2f070de25fe048c16b (patch)
treef6e77861c17325954af474e417e4c9c84382db27 /docs/handle-docs
parent6fd3e9232e76a8654292a868496bb052df092403 (diff)
handle-docs: add "how to handle documentation"
Change-Id: I309c44bc2199b330264e061367d57a4de41d4fbb Signed-off-by: Clément Bénier <clement.benier@iot.bzh>
Diffstat (limited to 'docs/handle-docs')
-rw-r--r--docs/handle-docs/abstract.md23
-rw-r--r--docs/handle-docs/documentation-usage.md90
-rw-r--r--docs/handle-docs/handle-docs.md33
3 files changed, 118 insertions, 28 deletions
diff --git a/docs/handle-docs/abstract.md b/docs/handle-docs/abstract.md
new file mode 100644
index 0000000..5734b2f
--- /dev/null
+++ b/docs/handle-docs/abstract.md
@@ -0,0 +1,23 @@
+# Abstract
+
+AGL doc website is based on a collection of markdown files fetched from various repositories.
+A tool available in [docs-tools](https://github.com/automotive-grade-linux/docs-tools) takes
+care of collecting and templating all markdown files according fetched_files.yml located in
+[docs-webtemplate](https://github.com/automotive-grade-linux/docs-webtemplate).
+
+See below a scheme of the workflow of agl documentation website generation.
+
+![alt text](pictures/workflow.png)
+
+As you can see, the section_``version``.yml contains the links to all the book yaml files, it is proceed to fetch all book yaml files from remote repositories to the docs-webtemplate. The book yaml files contains all the url to your markdown files from the remote repository.
+
+As soon as all the markdown files are fetched, the tools process to generate the AGL doc website.
+
+---
+
+**Note:**
+
+The images described in markdown files are automatically fetched. For that, the necessary condition is that in markdown files, the relative path has to match with the location of images.
+
+---
+
diff --git a/docs/handle-docs/documentation-usage.md b/docs/handle-docs/documentation-usage.md
new file mode 100644
index 0000000..2a1dcf7
--- /dev/null
+++ b/docs/handle-docs/documentation-usage.md
@@ -0,0 +1,90 @@
+# Documentation Usage
+
+The [docs-webtemplate](https://github.com/automotive-grade-linux/docs-webtemplate)
+repository contains AGL documentation website template, rendering is visible at
+<https://docs.automotivelinux.org.>
+This website relies on the generator located in
+[docs-tools](https://github.com/automotive-grade-linux/docs-tools).
+
+## Download Sources
+
+Get the ```setupdocs.sh``` script to initialize your environment.
+
+```bash
+wget https://raw.githubusercontent.com/automotive-grade-linux/docs-webtemplate/master/setupdocs.sh
+```
+
+This script fetches [docs-tools](https://github.com/automotive-grade-linux/docs-tools), install npm modules.
+
+```bash
+mkdir docs-webtemplate
+bash setupdocs.sh --directory=docs-webtemplate
+```
+
+For consulting help, do:
+
+```bash
+bash setupdocs.sh --help
+```
+
+## Building a local site
+
+In docs-webtemplate directory:
+
+```bash
+make serve
+```
+
+For cleaning your work, use:
+
+```bash
+make clean
+```
+
+## Documentation from local repositories
+
+It is also possible to use markdown files from local repositories.
+
+For local fetch, a specific file named ```__fetched_files_local.yml```
+was introduced.
+
+This file is used to overload ```url_fetch``` in section_<version>.yml
+in order to use local repositories on not remote ones.
+
+Thus, this file is needed to be added in the docs-webtemplate root,
+see an example below:
+
+```bash
+############__fetched_files_local.yml##############
+-
+ url_fetch : <pathToDocsSources>/docs-sources/
+ git_name : automotive-grade-linux/docs-sources
+-
+ url_fetch : <pathToXdsDocs>/xds-docs/
+ git_name : src/xds/xds-docs
+-
+ git_name: AGL/meta-renesas-rcar-gen3
+ url_fetch: <pathToMetaRenesas>/meta-renesas-rcar-gen3
+###################################################
+```
+
+It is also possible to use ```id``` instead of ```git_name```.
+
+## Test Hyperlinks
+
+[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to check all the hyperlinks in the site.
+
+For testing hyperlinks as soon as the local site is running, do:
+
+```bash
+make linkchecker
+```
+
+or
+
+```bash
+linkchecker http://localhost:4000
+```
+
+The ```linkchecker``` output will display the broken link and there location
+in the site.
diff --git a/docs/handle-docs/handle-docs.md b/docs/handle-docs/handle-docs.md
index 9ecb421..5a327a0 100644
--- a/docs/handle-docs/handle-docs.md
+++ b/docs/handle-docs/handle-docs.md
@@ -1,27 +1,4 @@
-# Abstract
-
-AGL doc website is based on a collection of markdown files fetched from various repositories.
-A tool available in [docs-tools](https://github.com/automotive-grade-linux/docs-tools) takes
-care of collecting and templating all markdown files according fetched_files.yml located in
-[docs-webtemplate](https://github.com/automotive-grade-linux/docs-webtemplate).
-
-See below a scheme of the workflow of agl documentation website generation.
-
-![alt text](pictures/workflow.png)
-
-As you can see, the section_``version``.yml contains the links to all the book yaml files, it is proceed to fetch all book yaml files from remote repositories to the docs-webtemplate. The book yaml files contains all the url to your markdown files from the remote repository.
-
-As soon as all the markdown files are fetched, the tools process to generate the AGL doc website.
-
----
-
-**Note:**
-
-The images described in markdown files are automatically fetched. For that, the necessary condition is that in markdown files, the relative path has to match with the location of images.
-
----
-
-## How to add a new documentation section into AGL documentation
+# How to add a new documentation section into AGL documentation
They are two steps to add new markdown files to AGL documentation:
@@ -34,7 +11,7 @@ They are two steps to add new markdown files to AGL documentation:
---
-### Add a book yaml file into a repository
+## Add a book yaml file into a repository
The book file is needed to describe how your documentation is structured and must be used to describe
among others :
@@ -73,7 +50,7 @@ There are several types of book:
- book
- api
-#### Book Type
+### Book Type
`book` type describes documentation structure and chapters.
Below the generic way to include a book file:
@@ -125,11 +102,11 @@ Here a sample yaml file, you can start from :
wget https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master-next/docs/getting-started-book.yml -O my-new-book.yml
```
-#### Api Type
+### Api Type
In progress
-### Add an entry in section file
+## Add an entry in section file
There are 4 sections in docs: getting_started, architecture_guides, developer_guides, apis_services.