--- 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 --- # 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_.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: ``_`` 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: 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_: title in 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_: Name of your subchapter in 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_: Name of your subchapter in url: "%lang%/relative-path/to/your/mardown.md" - name: Name of your subchapter name_: Name of your subchapter in - name: Name of your subsubchapter name_: Name of your subsubchapter in url: "%lang%/relative-path/to/your/mardown.md" - name: Name of your subsubchapter name_: Name of your subsubchapter in children: - ... - ... - ... - id: ... ``` [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: url_fetch: #optional, overload the default one 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: url_fetch: #optional, overload the default one git_commit: #optional, overload the default one path: "relativepath/from/root/repository/to/the/book/yaml/file" - ... - id: ... ```