diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..51b3edd --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +mkdocs.yml +.bundle/ +vendor/ +Gemfile.lock +html/ +projects/* +!projects/ +!projects/index.md +!projects/archive.md + +.idea/ +.DS_Store diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..a05f9b8 --- /dev/null +++ b/Gemfile @@ -0,0 +1,3 @@ +source 'https://rubygems.org' + +gem 'git' diff --git a/README.md b/README.md index f3ed78b..817a409 100644 --- a/README.md +++ b/README.md @@ -1 +1,72 @@ -# icinga-docs-tools \ No newline at end of file +# 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 | + + +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 +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 \ No newline at end of file diff --git a/build-docs.rb b/build-docs.rb new file mode 100755 index 0000000..8ba0a7a --- /dev/null +++ b/build-docs.rb @@ -0,0 +1,59 @@ +#!/usr/bin/env ruby +require 'fileutils' +require 'yaml' +require 'git' + +config = YAML::load_file('config.yml') +mkdocs = YAML::load_file('mkdocs.template.yml') + +config['projects'].each do |project_name, project_config| + puts "== #{project_name}" + + project_dir = config['projects_dir'] + '/' + project_config['target'] + + if project_config['latest'] == true + clone_target = project_dir + '/latest' + else + clone_target = project_dir + '/' + project_config['ref'].gsub('tags/', '') + end + + project_docs_dir = clone_target + '/' + project_config['docs_dir'] + pages = [] + + if File.directory?(clone_target) + puts 'Project already exists, cleaning up' + FileUtils.rm_rf(clone_target) + end + + puts 'Cloning ...' + FileUtils.mkdir_p(project_dir) + repo = Git.clone(project_config['git'], clone_target) + + puts "Switching to ref '#{project_config['ref']}'" + repo.branch(project_config['ref']).checkout + + puts 'Cleaning up everything not related to docs' + Dir::foreach(clone_target) do |file| + next if(file == project_config['docs_dir']) + next if(file == '.' || file == '..') + FileUtils.rm_rf(clone_target + '/' + file) + end + + puts "Building page index from #{project_docs_dir}" + Dir.glob("#{project_docs_dir}/*.md") do |file| + filepath = file.gsub('projects/', '') + filename = filepath.match(/(\d+)-(.*).md$/) + header = filename[2].gsub('-', ' ').split.map(&:capitalize).join(' ') + pages.push(header => filepath) + end + mkdocs['pages'].push(project_name => pages) + +end + +mkdocs['extra']['append_pages'].each do |name, target| + mkdocs['pages'].push(name => target) +end + +File.write('mkdocs.yml', mkdocs.to_yaml) + +%x( mkdocs build ) \ No newline at end of file diff --git a/config.yml b/config.yml new file mode 100644 index 0000000..eb91cf7 --- /dev/null +++ b/config.yml @@ -0,0 +1,27 @@ +--- +projects_dir: 'projects' +projects: + Icinga 2: + git: 'https://github.com/Icinga/icinga2.git' + ref: 'tags/v2.6.3' + latest: true + target: 'icinga2' + docs_dir: 'doc' + Icinga Web 2: + git: 'https://github.com/Icinga/icingaweb2.git' + ref: 'tags/v2.4.1' + latest: true + target: 'icingaweb2' + docs_dir: 'doc' + Director: + git: 'https://github.com/Icinga/icingaweb2-module-director.git' + ref: 'tags/v1.3.1' + latest: true + target: 'director' + docs_dir: 'doc' + Business Process: + git: 'https://github.com/Icinga/icingaweb2-module-businessprocess.git' + ref: 'tags/v2.1.0' + latest: true + target: 'businessprocess' + docs_dir: 'doc' diff --git a/mkdocs.template.yml b/mkdocs.template.yml new file mode 100644 index 0000000..64b3b37 --- /dev/null +++ b/mkdocs.template.yml @@ -0,0 +1,52 @@ +--- +site_name: Documentation +theme: material +theme_dir: theme +docs_dir: projects +site_dir: 'html' +pages: +- Introduction: index.md +extra: + append_pages: + Archive: archive.md + font: + text: 'Open Sans:300,400,400i,600,700' + menu: + - text: 'Products' + link: 'https://www.icinga.com/products/' + - text: 'Partners' + link: 'https://www.icinga.com/partners/' + - text: 'Training' + link: 'https://www.icinga.com/training/' + - text: 'Events' + link: 'https://www.icinga.com/events/' + - text: 'Docs' + link: 'https://www.icinga.com/docs/' + - text: 'Support' + link: 'https://www.icinga.com/support/' + - text: 'Blog' + link: 'https://www.icinga.com/blog/' + - text: 'Download' + link: 'https://www.icinga.com/downloads/' + cssid: 'download-button' + social: + - type: 'facebook' + link: 'https://www.facebook.com/icinga' + - type: 'twitter' + link: 'https://twitter.com/icinga' + - type: 'google-plus' + link: 'http://plus.google.com/+icinga' + - type: 'feed' + link: 'https://www.icinga.com/feed/' +extra_css: +- css/theme.css +extra_javascript: [] +markdown_extensions: + - smarty + - admonition + - codehilite(guess_lang=true) + - toc(permalink=true) +copyright: '2017 - Icinga Open Source Monitoring' +google_analytics: + - 'UA-280659-15' + - 'auto' diff --git a/projects/archive.md b/projects/archive.md new file mode 100644 index 0000000..5fa83fd --- /dev/null +++ b/projects/archive.md @@ -0,0 +1,6 @@ +# Archive +Here you will find older versions of documentations and docs of older products. + +#### Icinga 1 +* [English Online](https://www.icinga.com/docs/icinga1/latest/en/) +* [German Online](https://www.icinga.com/docs/icinga1/latest/de/) \ No newline at end of file diff --git a/projects/index.md b/projects/index.md new file mode 100644 index 0000000..4b35d92 --- /dev/null +++ b/projects/index.md @@ -0,0 +1,6 @@ +# Icinga Documentation + +Welcome to the Icinga Documation. Please select your preferred product on the left. + +Built on proven technologies and concepts as well as progressive frameworks and standards, Icinga is a product of the +community - their ideas, needs and combined passion for innovation. \ No newline at end of file diff --git a/theme/css/theme.css b/theme/css/theme.css new file mode 100644 index 0000000..0fe5ca4 --- /dev/null +++ b/theme/css/theme.css @@ -0,0 +1,352 @@ +.clearfix:after { + content: ""; + display: block; + clear: both; +} + +#main-header { + width: 100%; + float: left; + background: #000000; + position: relative; + color: #ffffff; +} + +#main-header-container { + width: 80%; + max-width: 1255px; + margin: auto; + position: relative; +} + +#main-header-logo-container { + float: left; + position: relative; + height: 64px; + line-height: 8.5em; + padding-top: 0.1em; + padding-left: 0.3em; +} + +#main-header-logo-container img{ + max-width: 100%; +} + +#logo { + float: none; + display: inline-block; + height: 38.39px; +} + +#top-menu-nav { + float: left; + line-height: 0; +} + +.top-menu-item a:hover { + opacity: .6; +} + +#top-menu-hamburger { + display:none; + color: white; + font-size: 32px; + color: #0095BF; +} + +#top-menu-nav ul { + list-style: none; + padding: 0; + margin: 0; +} + +#top-menu-nav li { + line-height: 2.9em; + position: relative; + font-size: 14px; + padding-right: 9px; + display: inline-block; +} + +#top-menu-nav a { + padding: 10px 12px; + font-weight: 600; + font-family: "Open Sans"; +} + +#main-header-navigation { + float: right; + font-weight: 600; + height: 100%; + padding: 1.1em 0; +} + +#download-button > a { + border: 1px solid white; + border-radius: 3px; +} + +.md-header { + background: url(../images/icinga-hero-background.jpg); + background-size: cover; + background-position: center; + background-repeat: no-repeat; + position: relative; + float: left; + width: 100%; + padding: 20px; + height: auto; + box-shadow: none; +} + +.md-header[data-md-state=shadow] { + box-shadow: none; +} + +.md-header-nav { + width: 80%; + position: relative; + margin: auto; + padding: 2% 0; +} + +.md-header-nav__title { + padding: 0; + font-size: 32px; + line-height: 1em; + font-family: "Open Sans"; + font-weight: 700; +} + +.md-container { + padding-top: 0; + font-family: "Open Sans" +} + +.md-content a { + color: #0095BF; +} + +.md-content a:hover { + color: #EF4F98; +} + +.md-nav__item a:hover { + color: #0095BF; +} + +.md-nav__link:hover { + color: #0095BF; +} + +.md-nav__link--active { + color: #0095BF; +} + +.md-nav--secondary { + border-left: .2rem solid #0095BF; +} + +.md-sidebar[data-md-state=lock] { + top: 1rem; +} + +#mkdocs-search-results { + font-family: "Open Sans" +} + +#search-loading { + display: table; + margin: 0 auto; + color: #EF4F98;; +} + +#search-loading p{ + color: #000000; + margin: 1em 0; +} + +#searchpage-form { + display: none; +} + +#mobile-search-form { + width: 100%; +} + +.mobile-search-form-input { + width: 100%; + border: 1px solid #c7c9cb; + line-height: 2em; + padding-left: 5px; +} + +#footer { + width: 100%; + background: #000000; +} + +.footer-container { + width: 80%; + position: relative; + margin: auto; + text-align: left; +} + +#footer-widgets { + padding: 6% 0 0; +} + +.footer-widget { + margin: 0 5.5% 5.5% 0; + font-size: 13px; + float: left; + color: #ffffff; + line-height: 1.7em; + width: 20.875%; +} + +.footer-widget h4 { + font-size: 22px; +} + +.footer-widget-text { + float: left; + max-width: 100%; +} + +.footer-widget-text:last-child { + margin-bottom: 0 !important; +} + +.textwidget ul { + list-style: none; + margin: 0; + padding: 0; + line-height: 1.7em; +} + +.textwidget ul li { + margin-bottom: 0.5em; +} + +.footer-title { + margin: 0; + padding: 0; + padding-bottom: 10px; +} + +.footer-menu-item a:hover { + opacity: .6; +} + +.footer-logo { + padding-top: 15px; + height: 70px; +} + +.footer-logo:hover { + opacity: .6; +} + +#stay-informed-email { + padding: 5px; + font-size: 14px; + width: 100%; + border: 1px solid #bbb; + color: #4e4e4e; + background-color: #fff; +} + +#submit-button { + margin-left: 0px; + margin-top: 10px; + background-color: #0095bf; + font-size: 14px; + font-weight: 500; + border-radius: 2px; + border: 2px solid transparent; + color: #ffffff; + width: 100%; + line-height: 1.4em; +} + +.footer-bottom { + padding: 15px 0 5px; + color: #ffffff; +} + +#footer-social-icons { + list-style: none; + float: right; + margin: 0; + padding: 0; + font-size: 18px; +} + +.footer-social-icon { + display: inline-block; + margin-left: 20px; +} + +#footer-copyright { + font-size: 13px; + padding-bottom: 17px; +} + +@media screen and (max-width:65em) { + #top-menu { + display: none; + position: absolute; + left: 0; + right: 0; + z-index: 999; + background-color: #000000; + border-top: 4px solid #0095BF; + padding: 5%; + } + + #top-menu-hamburger { + display: block; + } + + #top-menu-nav li { + display: block; + padding-top: 10px; + padding-bottom: 20px; + } + + #download-button > a { + border: none; + } + + .md-search__form { + display: none; + } + + .md-header-nav__button.md-icon--search { + display: block; + } + + #searchpage-form { + display: table; + margin: 0px 0px 50px 0px; + width: 30%; + } + + #search-loading { + display: none; + } + + .footer-widget:nth-child(n) { + width: 42% !important; + margin: 0 7.5% 7.5% 0 !important; + } +} + + +@media only screen and (max-width: 76.1875em) { + html .md-nav--primary .md-nav__title--site { + background-color: #0095BF; + } +} \ No newline at end of file diff --git a/theme/images/icinga-hero-background.jpg b/theme/images/icinga-hero-background.jpg new file mode 100644 index 0000000..cf76bc4 Binary files /dev/null and b/theme/images/icinga-hero-background.jpg differ diff --git a/theme/images/icinga-logo-white.png b/theme/images/icinga-logo-white.png new file mode 100644 index 0000000..7e6c379 Binary files /dev/null and b/theme/images/icinga-logo-white.png differ diff --git a/theme/partials/footer.html b/theme/partials/footer.html new file mode 100644 index 0000000..e2dc44c --- /dev/null +++ b/theme/partials/footer.html @@ -0,0 +1,73 @@ + \ No newline at end of file diff --git a/theme/partials/header.html b/theme/partials/header.html new file mode 100644 index 0000000..7b7df7c --- /dev/null +++ b/theme/partials/header.html @@ -0,0 +1,46 @@ +
+
+
+ + + +
+
+ +
+
+
+ +
+ +
\ No newline at end of file diff --git a/theme/search.html b/theme/search.html new file mode 100644 index 0000000..a91bd50 --- /dev/null +++ b/theme/search.html @@ -0,0 +1,34 @@ +{% extends "base.html" %} + +{% block extrahead %} + + +{% endblock %} + +{% block content %} +

Search Results

+ + + +
+
+ + +
+
+ +
+
+ +

Searching ...

+
+
+ +{% endblock %} \ No newline at end of file