diff options
Diffstat (limited to 'docs/5_How_To')
| -rw-r--r-- | docs/5_How_To/1_Abstract.md | 32 | ||||
| -rw-r--r-- | docs/5_How_To/2_Usage.md | 99 | ||||
| -rw-r--r-- | docs/5_How_To/3_How_to_add_documentation_to_AGL.md | 148 | ||||
| -rw-r--r-- | docs/5_How_To/pictures/workflow.png | bin | 206125 -> 0 bytes |
4 files changed, 0 insertions, 279 deletions
diff --git a/docs/5_How_To/1_Abstract.md b/docs/5_How_To/1_Abstract.md deleted file mode 100644 index 63561fb..0000000 --- a/docs/5_How_To/1_Abstract.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -edit_link: '' -title: Abstract -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/handle-docs/abstract.md ---- - -<!-- 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 --> - -# 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. - - - -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/5_How_To/2_Usage.md b/docs/5_How_To/2_Usage.md deleted file mode 100644 index 07b165b..0000000 --- a/docs/5_How_To/2_Usage.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -edit_link: '' -title: Usage -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/handle-docs/documentation-usage.md ---- - -<!-- 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 --> - -# 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/5_How_To/3_How_to_add_documentation_to_AGL.md b/docs/5_How_To/3_How_to_add_documentation_to_AGL.md deleted file mode 100644 index 679824a..0000000 --- a/docs/5_How_To/3_How_to_add_documentation_to_AGL.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -edit_link: '' -title: How to add documentation to AGL -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/handle-docs/handle-docs.md ---- - -<!-- 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 --> - -# How to add a new documentation section into AGL documentation - -They are two steps to add new markdown files to AGL documentation: - -- Add a book yaml file to the repository where the documentation sources are located (written in markdown files). -- Add an entry into the global section yaml file that point to your book file. The section yaml file is in [docs-webtemplate](https://github.com/automotive-grade-linux/docs-webtemplate) repository (`git@github.com:automotive-grade-linux/docs-webtemplate.git`) named `section_<version>.yml`. - ---- - -**Note**: To generate a local documentation please refer to the [README](https://github.com/automotive-grade-linux/docs-webtemplate/blob/master-next/README.md) of the docs-webtemplate (https://github.com/automotive-grade-linux/docs-webtemplate) and use `setupdocs.sh` script. - ---- - -## 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 : - -- the global title of the doc -- the chapter name when the doc will be part of the whole documentation website -- subchapters list and consequently subchapters hierarchy -- multi-language description - ---- - -**Note:** - -Multi-language is handled by key suffixes. That is to say, there are some keys that can be suffixed by a language: ``<key>_<lang>`` -For the url to the markdown files, the prefix ```%lang%``` will match with suffixes. So, you have to create a subdirectory named ```%lang%``` where the markdown files are put. - -A example for the french: - -``` -name: "My section in english" -name_fr: "Ma section en français" -url: "%lang/section.md" -``` - -``` -$ ls -lR mydir -book.yml -section.md -fr/section.md -``` - ---- - -There are several types of book: - -- book -- api - -### Book Type - -`book` type describes documentation structure and chapters. -Below the generic way to include a book file: - -```yaml -type: books -books: -- - id: <ID1> - order: x #optional: between 0 in 100 default when not set is 50, it allows to define order in final - #documentation, more the order number is low more the documentation is first - title: title of your chapter #default title - title_<lang>: title in <lang> - description: description of your book - keywords: some keywords - author: author of the documentation - version: version of the documentation - chapters: - - name: Name of your subchapter - name_<lang>: Name of your subchapter in <lang> - url: "%lang%/relative-path/to/your/mardown.md" #%lang% will be replaced by the - #available languages, - #default language can be in the root directory - - name: Name of your subchapter - name_<lang>: Name of your subchapter in <lang> - url: "%lang%/relative-path/to/your/mardown.md" - - name: Name of your subchapter - name_<lang>: Name of your subchapter in <lang> - - name: Name of your subsubchapter - name_<lang>: Name of your subsubchapter in <lang> - url: "%lang%/relative-path/to/your/mardown.md" - - name: Name of your subsubchapter - name_<lang>: Name of your subsubchapter in <lang> - children: - - ... - - ... - - ... -- - id: <ID2> - ... -``` - -[book.yml.in](https://github.com/automotive-grade-linux/docs-sources/blob/master/docs/handle-docs/book.yml.in) -is a sort of schema of book.yml. This file contains all supported keys. - -Here a sample yaml file, you can start from : - -```bash -wget https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master-next/docs/getting-started-book.yml -O my-new-book.yml -``` - -### Api Type - -In progress - -## Add an entry in section file - -There are 4 sections in docs: getting_started, architecture_guides, developer_guides, apis_services. - -They are located in `content/docs` in [docs-webtemplate](https://github.com/automotive-grade-linux/docs-webtemplate) repository. -In addition, each directory contains several section yaml file, one a version. For master version, it is `section_master.yml`. - -Below the structure of section yaml file. - -```yaml -url_fetch : DEFAULT_URL_FETCH #this the default url_fetch that can be overload further, there already are some default variables defined in docs-webtemplate/docs-tools -git_commit : DEFAULT_VERSION #this is the default git_commit that can be overload further, there already are some default variables defined in docs-webtemplate/docs-tools - -name: Name of the section -template: generated_index.html -books: -- - id: <ID1> - url_fetch: <url_fetch> #optional, overload the default one - git_commit: <git_commit> #optional, overload the default one - path: "relativepath/from/root/repository/to/the/book/yaml/file" - books: #optional: subbooks, will be a child of the above book - - id: <SUBID2> - url_fetch: <url_fetch> #optional, overload the default one - git_commit: <git_commit> #optional, overload the default one - path: "relativepath/from/root/repository/to/the/book/yaml/file" - - ... -- - id: <ID2> - ... -``` diff --git a/docs/5_How_To/pictures/workflow.png b/docs/5_How_To/pictures/workflow.png Binary files differdeleted file mode 100644 index 75466e5..0000000 --- a/docs/5_How_To/pictures/workflow.png +++ /dev/null |
