2.8 KiB

Raw Blame History

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:

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:

user@localhost ~/ $ pip install mkdocs
user@localhost ~/ $ pip install mkdocs-material

Clone this repository and install dependencies:

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:

user@localhost ~/ $ mkdocs serve

You should be able to access the documentation now in your browser by calling the address https://localhost:8000

2.8 KiB Raw Blame History