From a216ea0e2e67b571926bf978c393ec51de02b9d9 Mon Sep 17 00:00:00 2001 From: Clément Bénier Date: Tue, 16 Apr 2019 18:40:29 +0200 Subject: handle-docs: add "how to handle documentation" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: I309c44bc2199b330264e061367d57a4de41d4fbb Signed-off-by: Clément Bénier --- docs/handle-docs-book.yml | 8 ++- docs/handle-docs/abstract.md | 23 +++++++++ docs/handle-docs/documentation-usage.md | 90 +++++++++++++++++++++++++++++++++ docs/handle-docs/handle-docs.md | 33 ++---------- 4 files changed, 124 insertions(+), 30 deletions(-) create mode 100644 docs/handle-docs/abstract.md create mode 100644 docs/handle-docs/documentation-usage.md diff --git a/docs/handle-docs-book.yml b/docs/handle-docs-book.yml index 34017a9..3eca835 100644 --- a/docs/handle-docs-book.yml +++ b/docs/handle-docs-book.yml @@ -2,12 +2,16 @@ type: books books: - id: handle-docs - title: "Add your documentation to AGL" + title: "How to handle documentation" description: keywords: author: version: master chapters: + - url: "handle-docs/abstract.md" + name: Abstract + - url: "handle-docs/documentation-usage.md" + name: Usage - url: "handle-docs/handle-docs.md" - name: Handle documentation + name: How to add documentation to AGL 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 + +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_.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 : /docs-sources/ + git_name : automotive-grade-linux/docs-sources +- + url_fetch : /xds-docs/ + git_name : src/xds/xds-docs +- + git_name: AGL/meta-renesas-rcar-gen3 + url_fetch: /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. -- cgit 1.2.3-korg