To make our and other lives less painful writing documentation is a good start to decrease the level of frustration when working on a shared project.

It's a common feeling writing documentation isn't something we are all waiting for to do. In an effort to make it easier for all of us an automatically way of deployment can be managed by our good friend jenkins in combination with docker.

The details about this flow is been described on this page. After reading through this documentation section you should be aware of the general deployment idea so you can implement it yourself and start writing documentation without any hassle.

Mark down

The goal is that you write documentation using mark down in a git repository, that way you can easily write together with others on the same documentation in a structured and versionned manner.

By using mark down we can easily convert those md documents to whatever you want and gives us an easy syntax to write documentation.

Mkdocs

Using mkdocs a nice and easy manner has been found to generate a clean static html site based on the md files without much effort.

The installation is quite straight forward using python-pip:

$ sudo pip install mkdocs

Once the installation process ended successfully you should be able to run the mkdocs engine:

A brand new shiny rpm package artifact then could be archived so the next step in the flow could use it.

Repository

The rpm artifact of the package-doc job could then be used to deploy on your favorite repository service, from createrepo, pulp, yum-repo-server, prm to packagecloud so the next job can be triggered to install/update the package on your webserver

Deploy-package

Next you could configure a jenkins job which for examples logs in through ssh and installs the package you've pushed to your repository.

Configuration management

Instead of the deployment-package job you could also use a configuration management tool which does the installation/upgrade for you ;)

Docker

Instead of installing the tools on your local machine or your build server you could also opt for docker, there are a lot of preconfigured docker containers available on the internet or you could start making your own docker file relying on for example a centos official docker container and only mount your markdown documents into the container. That way you have more control over the environment and releases independent of the host system both by the ones who are writing the documentation as your build system..