Icinga Documentation

This repository includes scripts to build the documentation for all Icinga projects.

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 them. The ordering is defined by the file names. The capitalized name of each file is used as a title for this documentation section. The generates the mkdocs.yml file.

Usage

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

config.yml

This file defines generally for which project documentation should be build.

General settings:

Option	Description
site_name	The site_name is displayed as title on the generated page
source_dir'	Target directory to store the documentation source.
site_dir	Target directory for generated html
project	General project settings

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:

site_name: 'Icinga 2'
source_dir: 'www/source'
site_dir: 'www/html'
project:
  git: 'https://github.com/Icinga/icinga2.git'
  ref: 'support/2.7'
  target: 'icinga2'
  docs_dir: 'doc'
  latest: true

Example with subcategories:

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'
  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

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 in version 1.12.2:

user@localhost ~/ $ pip install mkdocs==0.16.3
user@localhost ~/ $ pip install mkdocs-material==1.12.2

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

Create and configure configuration file:

user@localhost ~/ $ cp config.example.yml config.yml
user@localhost ~/ $ vim config.yml

Build documentation:

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