73 lines
2.8 KiB
Markdown
73 lines
2.8 KiB
Markdown
# Icinga Documentation
|
|
This repository includes everything for building the documentation for all tools in the Icinga ecosystem.
|
|
|
|
The `build-docs.rb` script clones each configured project to the specified directory and switches to the specified
|
|
branch. It searches for `*.md` files within the configured directory and creates documentation sections out of the found
|
|
files. 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`
|
|
|
|
## Configuration
|
|
|
|
### `config.yml`
|
|
This file defines generally for which projects documentation should be build. All settings are required.
|
|
|
|
| Option | Description |
|
|
| ------------- | ----------------------------------------------------------------------- |
|
|
| `projects_dir` | Directory where all projects are stored |
|
|
| `projects` | Array of projects |
|
|
| `git` | Git repository |
|
|
| `ref` | Branch or Tag to check out |
|
|
| `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 |
|
|
|
|
|
|
Example:
|
|
|
|
``` yaml
|
|
projects_dir: 'projects'
|
|
projects:
|
|
Icinga 2:
|
|
git: 'https://github.com/Icinga/icinga2.git'
|
|
ref: 'tags/v2.6.3'
|
|
target: 'icinga2'
|
|
docs_dir: 'doc'
|
|
Icinga Web 2:
|
|
git: 'https://github.com/Icinga/icingaweb2.git'
|
|
ref: 'tags/v2.4.1'
|
|
target: 'icingaweb2'
|
|
docs_dir: 'doc'
|
|
```
|
|
|
|
### `mkdocs.template.yml`
|
|
This file is used as a template for the final `mkdocs.yml`. Default settings and some other configuration options are
|
|
here.
|
|
|
|
### Run Development Server
|
|
To see a live preview of the documentation you can run a development server that will refresh automatically on changes.
|
|
|
|
|
|
Install `mkdocs` and the `material` theme:
|
|
|
|
``` bash
|
|
user@localhost ~/ $ pip install mkdocs
|
|
user@localhost ~/ $ pip install mkdocs-material
|
|
```
|
|
|
|
Clone this repository and install dependencies:
|
|
|
|
``` bash
|
|
user@localhost ~/ $ git clone https://github.com/Icinga/icinga-docs-tools.git
|
|
user@localhost ~/ $ cd icinga-docs-tools
|
|
user@localhost ~/ $ bundle install --path vendor
|
|
user@localhost ~/ $ bundle exec build-docs.rb
|
|
```
|
|
|
|
Run server:
|
|
|
|
``` bash
|
|
user@localhost ~/ $ mkdocs serve
|
|
```
|
|
|
|
You should be able to access the documentation now in your browser by calling the address https://localhost:8000 |