From feb221c5df277747cae340aa0e9fa3c0e99cef92 Mon Sep 17 00:00:00 2001
From: Darko Poljak <foss@ungleich.com>
Date: Fri, 1 Sep 2017 10:40:01 +0200
Subject: [PATCH] Improve configuration docs.

---
 docs/src/cdist-configuration.rst | 91 ++++++++++++++++++++++++++++++++
 docs/src/index.rst               |  1 +
 docs/src/man1/cdist.rst          | 15 +++---
 3 files changed, 99 insertions(+), 8 deletions(-)
 create mode 100644 docs/src/cdist-configuration.rst

diff --git a/docs/src/cdist-configuration.rst b/docs/src/cdist-configuration.rst
new file mode 100644
index 00000000..6a0e4a4f
--- /dev/null
+++ b/docs/src/cdist-configuration.rst
@@ -0,0 +1,91 @@
+Configuration
+=============
+
+Description
+-----------
+cdist obtains configuration data from the following sources in the following
+order:
+
+    #. command-line options
+    #. configuration file specified at command-line using -g command line option
+    #. configuration file specified in CDIST_CONFIG_FILE environment variable
+    #. environment variables
+    #. user's configuration file (first one found of ~/.cdist.cfg, $XDG_CONFIG_HOME/cdist/cdist.cfg, in specified order)
+    #. system-wide configuration file (/etc/cdist.cfg)
+
+if one exists.
+
+Configuration source with lower ordering number from above has a higher
+precedence. Configuration option value read from source with higher
+precedence will overwrite option value, if exists, read from source with
+lower precedence. That means that command-line option wins them all.
+
+Users can decide on the local conifguration file location. It can be either
+~/.cdist.cfg or $XDG_CONFIG_HOME/cdist/cdist.cfg. Note that, if both exist,
+then ~/.cdist.cfg is used.
+
+For a per-project configuration, particular environment variables or better,
+CDIST_CONFIG_FILE environment variable or -g CONFIG_FILE command line option,
+can be used.
+
+Config file format
+------------------
+cdist configuration file is in the INI file format. Currently it supports
+only [GLOBAL] section.
+The possible keywords and their meanings are as follows:
+
+:strong:`archiving`
+    Use specified archiving. Valid values include:
+    'none', 'tar', 'tgz', 'tbz2' and 'txz'.
+
+:strong:`beta`
+    Enable beta functionality. It recognizes boolean values from
+    'yes'/'no', 'on'/'off', 'true'/'false' and '1'/'0'
+
+:strong:`cache_path_pattern`
+    Specify cache path pattern.
+
+:strong:`conf_dir`
+    Comma separated list of configuration directories.
+    If also specified at command line then values from command line are
+    appended to this value.
+
+:strong:`init_manifest`
+    Specify default initial manifest.
+
+:strong:`inventory_dir`
+    Specify inventory directory.
+
+:strong:`jobs`
+    Specify number of jobs for parallel processing. If -1 then the default,
+    number of CPU's in the system is used. If 0 then parallel processing in
+    jobs is disabled. If set to positive number then specified maximum
+    number of processes will be used.
+
+:strong:`local_shell`
+    Shell command used for local execution.
+
+:strong:`out_path`
+    Directory to save cdist output in.
+
+:strong:`parallel`
+    Process hosts in parallel. If -1 then the default, number of CPU's in
+    the system is used. If 0 then parallel processing of hosts is disabled.
+    If set to positive number then specified maximum number of processes
+    will be used.
+
+:strong:`remote_copy`
+    Command to use for remote copy (should behave like scp).
+
+:strong:`remote_exec`
+    Command to use for remote execution (should behave like ssh).
+
+:strong:`remote_out_path`
+    Directory to save cdist output in on the target host.
+
+:strong:`remote_shell`
+    Shell command at remote host used for remote execution.
+
+:strong:`verbosity`
+    Set verbosity level. Valid values are: 
+    'ERROR', 'WARNING', 'INFO', 'VERBOSE', 'DEBUG', 'TRACE' and 'OFF'.
diff --git a/docs/src/index.rst b/docs/src/index.rst
index 42c21199..652c6082 100644
--- a/docs/src/index.rst
+++ b/docs/src/index.rst
@@ -18,6 +18,7 @@ Contents:
    cdist-quickstart
    man1/cdist
    cdist-bootstrap
+   cdist-configuration
    cdist-manifest
    cdist-type
    cdist-types
diff --git a/docs/src/man1/cdist.rst b/docs/src/man1/cdist.rst
index b6b2e04d..0e258d8c 100644
--- a/docs/src/man1/cdist.rst
+++ b/docs/src/man1/cdist.rst
@@ -473,21 +473,20 @@ usage. Its primary use is for debugging type parameters.
     be POSIX compatible shell.
 
 
-CONFIGURATION FILE
-------------------
+CONFIGURATION
+-------------
 cdist obtains configuration data from the following sources in the following
-order:
+order (from higher to lower precedence):
 
     #. command-line options
     #. configuration file specified at command-line
     #. configuration file specified in CDIST_CONFIG_FILE environment variable
     #. environment variables
-    #. user's configuration file (first one found of ~/.cdist.cfg,
-           $XDG_CONFIG_HOME/cdist/cdist.cfg, in specified order)
-    #. system-wide configuration file (/etc/cdist.cfg)
-
-if one exists.
+    #. user's configuration file (first one found of ~/.cdist.cfg, $XDG_CONFIG_HOME/cdist/cdist.cfg, in specified order)
+    #. system-wide configuration file (/etc/cdist.cfg).
 
+CONFIGURATION FILE FORMAT
+~~~~~~~~~~~~~~~~~~~~~~~~~
 cdist configuration file is in the INI file format. Currently it supports
 only [GLOBAL] section.
 The possible keywords and their meanings are as follows: