[doc] Add config reference guide

Masakari monitors are missing available configuration options
in its documentation which makes hard to configure them for users.

This patch adds automaticually generated reference about
available configuration options with their descriptions and defaults.

Change-Id: I2abc2afa6ae207c64186ab34b51a13c174cbf235

.gitignore

@@ -60,3 +60,9 @@ releasenotes/build
 
 # PyCharm IDE
 .idea/
+
+# configuration sample generation
+etc/masakarimonitors/masakarimonitors.conf.sample
+
+# File/s created by doc build
+doc/source/_static/masakarimonitors.conf.sample

doc/source/conf.py

@@ -23,6 +23,8 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     'openstackdocstheme',
+    'oslo_config.sphinxconfiggen',
+    'oslo_config.sphinxext',
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -75,3 +77,8 @@ latex_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'http://docs.python.org/': None}
+
+# sphinxcontrib.apidoc options
+config_generator_config_file = (
+    '../../etc/masakarimonitors/masakarimonitors-config-generator.conf')
+sample_config_basename = '_static/masakarimonitors'

doc/source/index.rst

@@ -9,11 +9,13 @@ Welcome to masakari-monitors's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    readme
    installation
    usage
+   reference/conf
+   reference/conf-file
 
 For Contributors
 ================

doc/source/reference/conf-file.rst

@@ -0,0 +1,23 @@
+.. _monitors-config-file:
+
+-------------------------------------------
+Masakari Monitors Sample Configuration File
+-------------------------------------------
+
+Configure Masakari Monitors by editing
+/etc/masakarimonitors/masakarimonitors.conf.
+
+No config file is provided with the source code, it will be created during
+the installation. In case where no configuration file was installed, one
+can be easily created by running::
+
+    tox -e genconfig
+
+
+To see configuration options available, please refer to :ref:`monitors-config`.
+
+.. only:: html
+
+   The following is a sample monitors configuration for adaptation and use.
+
+   .. literalinclude:: ../_static/masakarimonitors.conf.sample

doc/source/reference/conf.rst

@@ -0,0 +1,12 @@
+.. _monitors-config:
+
+---------------------------------------
+Masakari Monitors Configuration Options
+---------------------------------------
+
+The following is an overview of all available configuration options in
+masakari-monitors.
+To see sample configuration file, see :ref:`monitors-config-file`.
+
+.. show-options::
+   :config-file: etc/masakarimonitors/masakarimonitors-config-generator.conf