tyler.durden
/
icinga-docs-tools
mirror of https://github.com/Icinga/icinga-docs-tools.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README.md

This commit is contained in:
Blerim Sheqa 2017-10-19 10:45:32 +02:00
parent af82165502
commit f11f4ce64c
1 changed files with 67 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
README.md
View File

@ -1,43 +1,82 @@
# Icinga Documentation # Icinga Documentation
This repository includes everything for building the documentation for all tools in the Icinga ecosystem. This repository includes scripts to build the documentation for all Icinga projects.
The `build-docs.rb` script clones each configured project to the specified directory and switches to the specified The `build-docs.rb` script clones the configured project to a certain directory and switches to the specified
branch. It searches for `*.md` files within the configured directory and creates documentation sections out of the found branch. It searches for `*.md` files within the configured directory and creates documentation sections out of them.
files. The ordering is defined by the file names. The capitalized name of each file is used as a title for this documentation The ordering is defined by the file names. The capitalized name of each file is used as a title for this documentation
section. The script will generate the `mkdocs.yml` section. The generates the `mkdocs.yml` file.
## Usage
``` bash
Usage: build-docs.rb -c config.yml -t mkdocs.template.yml}
-f, --config FILENAME Configuration file with project definition. Defaults to "config.yml"
-t, --template FILENAME This file is used as template for the generated mkdocs.yaml. Defaults to "mkdocs.template.yml"
-h, --help Show this message
```
## Configuration ## Configuration
### `config.yml` ### `config.yml`
This file defines generally for which projects documentation should be build. All settings are required. This file defines generally for which project documentation should be build.
General settings:
| Option | Description | | Option | Description |
| ------------- | ----------------------------------------------------------------------- | | ------------- | ------------------------------------------------------------ |
| `projects_dir` | Directory where all projects are stored | | `site_name` | The `site_name` is displayed as title on the generated page |
| `projects` | Array of projects | | `source_dir'` | Target directory to store the documentation source. |
| `git` | Git repository | | `site_dir` | Target directory for generated html |
| `ref` | Branch or Tag to check out | | `project` | General project settings |
| `latest` | If set to `true`, the project will be cloned into a `latest` directory. |
| `target` | Target directory within `projects_dir` |
| `docs_dir` | Directory that includes the `*.md` files |
| `category` | If set, the projects will be displayed under this category |
Project settings:
| Option | Description |
| --------------- | ------------------------------------------------------------ |
| `git` | Git repository to clone |
| `ref` | Git branch or tag to checkout. For tags use `tags/v1.1.0` notation |
| `target` | A unique name to define the target. This is added to `source_dir` and `site_dir` |
| `docs_dir` | Directory within the repository that includes documentation files. Eg. `doc` |
| `latest` | If set to `true`, this documentation will be marked as the latest. This is important for the URLs. |
| `subcategories` | A project may include one ore more sub categories. One sub category may have one or more sub projects |
Subcategories are optional. They allow you to display a project documentation within another project documentation.
We need this for Icinga Web 2 and Director.
Example: Example:
``` yaml ``` yaml
projects_dir: 'projects' site_name: 'Icinga 2'
projects: source_dir: 'www/source'
Icinga 2: site_dir: 'www/html'
project:
git: 'https://github.com/Icinga/icinga2.git' git: 'https://github.com/Icinga/icinga2.git'
ref: 'tags/v2.6.3' ref: 'support/2.7'
target: 'icinga2' target: 'icinga2'
docs_dir: 'doc' docs_dir: 'doc'
Icinga Web 2: latest: true
git: 'https://github.com/Icinga/icingaweb2.git' ```
ref: 'tags/v2.4.1'
target: 'icingaweb2' Example with subcategories:
``` yaml
site_name: 'Director'
source_dir: 'www/source'
site_dir: 'www/html'
project:
git: 'https://github.com/Icinga/icingaweb2-module-director.git'
ref: 'support/1.4'
target: 'director'
docs_dir: 'doc' docs_dir: 'doc'
latest: true
subcategories:
Modules:
PuppetDB:
git: 'https://github.com/Icinga/icingaweb2-module-puppetdb.git'
ref: 'master'
target: 'puppetdb'
docs_dir: 'puppetdb/doc'
``` ```
### `mkdocs.template.yml` ### `mkdocs.template.yml`