Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 

README.md

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

About

Build environment for docs.icinga.com

Topics

Resources

Releases

No releases published

Packages

No packages published
You can’t perform that action at this time.