2340f1f2c5
This update enables markdown files in the template directory to include other files from the same directory, providing full support for Jinja templates. Previously, when a file included another file that was naturally ordered before it, the templates were already resolved due to in-place modifications. Now, rather than modifying template files directly and renaming them later, they are written to the target location instead.
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. |
subprojects |
A project may include one ore more sub-projects. |
Subprojects are optional. They allow you to display a project documentation within another project documentation. We need this for Icinga Web 2, Icinga Director and other projects where we summarise multiple repositories into one documentation.
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 subprojects:
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
subprojects:
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.
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:
Build documentation:
user@localhost ~/ $ bundle exec build-docs.rb -f examples/businessprocess-latest.yml
Run server:
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:6.1.0
You should be able to access the documentation now in your browser by calling the address https://localhost:8000