Improve module documentation and doc cleanup.

This adds lots of config module documentation in a standard format.
It will greatly improve the content at readthedocs.
Additionally:
 * Add a 'doc' env to tox.ini
 * Changed default highlight language for sphinx conf from python to yaml
   most examples in documentation are yaml configs
 * Updated datasource examples to highlight sh code properly

1 files changed, 167 insertions, 82 deletions

diff --git a/cloudinit/config/cc_rsyslog.py b/cloudinit/config/cc_rsyslog.py
index b8642d65..48f18620 100644
--- a/cloudinit/config/cc_rsyslog.py
+++ b/cloudinit/config/cc_rsyslog.py
@@ -18,90 +18,175 @@
 #    You should have received a copy of the GNU General Public License
 #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 """
-rsyslog module allows configuration of syslog logging via rsyslog
-Configuration is done under the cloud-config top level 'rsyslog'.
-
-Under 'rsyslog' you can define:
-  - configs:  [default=[]]
-    this is a list.  entries in it are a string or a dictionary.
-    each entry has 2 parts:
-       * content
-       * filename
-    if the entry is a string, then it is assigned to 'content'.
-    for each entry, content is written to the provided filename.
-    if filename is not provided, its default is read from 'config_filename'
-
-    Content here can be any valid rsyslog configuration.  No format
-    specific format is enforced.
-
-    For simply logging to an existing remote syslog server, via udp:
-      configs: ["*.* @192.168.1.1"]
-
-  - remotes: [default={}]
-    This is a dictionary of name / value pairs.
-    In comparison to 'config's, it is more focused in that it only supports
-    remote syslog configuration.  It is not rsyslog specific, and could
-    convert to other syslog implementations.
-
-    Each entry in remotes is a 'name' and a 'value'.
-     * name: an string identifying the entry.  good practice would indicate
-       using a consistent and identifiable string for the producer.
-       For example, the MAAS service could use 'maas' as the key.
-     * value consists of the following parts:
-       * optional filter for log messages
-         default if not present: *.*
-       * optional leading '@' or '@@' (indicates udp or tcp respectively).
-         default if not present (udp): @
-         This is rsyslog format for that. if not present, is '@'.
-       * ipv4 or ipv6 or hostname
-         ipv6 addresses must be in [::1] format. (@[fd00::1]:514)
-       * optional port
-         port defaults to 514
-
-  - config_filename: [default=20-cloud-config.conf]
-    this is the file name to use if none is provided in a config entry.
-
-  - config_dir: [default=/etc/rsyslog.d]
-    this directory is used for filenames that are not absolute paths.
-
-  - service_reload_command: [default="auto"]
-    this command is executed if files have been written and thus the syslog
-    daemon needs to be told.
-
-Note, since cloud-init 0.5 a legacy version of rsyslog config has been
-present and is still supported. See below for the mappings between old
-value and new value:
-   old value           -> new value
-   'rsyslog'           -> rsyslog/configs
-   'rsyslog_filename'  -> rsyslog/config_filename
-   'rsyslog_dir'       -> rsyslog/config_dir
-
-the legacy config does not support 'service_reload_command'.
-
-Example config:
-  #cloud-config
-  rsyslog:
-    configs:
-      - "*.* @@192.158.1.1"
-      - content: "*.*   @@192.0.2.1:10514"
-        filename: 01-example.conf
-      - content: |
-        *.*   @@syslogd.example.com
-    remotes:
-      maas: "192.168.1.1"
-      juju: "10.0.4.1"
-    config_dir: config_dir
-    config_filename: config_filename
-    service_reload_command: [your, syslog, restart, command]
-
-Example Legacy config:
-  #cloud-config
-  rsyslog:
-    - "*.* @@192.158.1.1"
-  rsyslog_dir: /etc/rsyslog-config.d/
-  rsyslog_filename: 99-local.conf
+Rsyslog
+-------
+**Summary:** configure system loggig via rsyslog
+
+This module configures remote system logging using rsyslog.
+
+The rsyslog config file to write to can be specified in ``config_filename``,
+which defaults to ``20-cloud-config.conf``. The rsyslog config directory to
+write config files to may be specified in ``config_dir``, which defaults to
+``/etc/rsyslog.d``.
+
+A list of configurations for for rsyslog can be specified under the ``configs``
+key in the ``rsyslog`` config. Each entry in ``configs`` is either a string or
+a dictionary. Each config entry contains a configuration string and a file to
+write it to. For config entries that are a dictionary, ``filename`` sets the
+target filename and ``content`` specifies the config string to write. For
+config entries that are only a string, the string is used as the config string
+to write. If the filename to write the config to is not specified, the value of
+the ``config_filename`` key is used. A file with the selected filename will
+be written inside the directory specified by ``config_dir``.
+
+The command to use to reload the rsyslog service after the config has been
+updated can be specified in ``service_reload_command``. If this is set to
+``auto``, then an appropriate command for the distro will be used. This is the
+default behavior. To manually set the command, use a list of command args (e.g.
+``[systemctl, restart, rsyslog]``).
+
+Configuration for remote servers can be specified in ``configs``, but for
+convenience it can be specified as key value pairs in ``remotes``. Each key
+is the name for an rsyslog remote entry. Each value holds the contents of the
+remote config for rsyslog. The config consists of the following parts:
+
+    - filter for log messages (defaults to ``*.*``)
+    - optional leading ``@`` or ``@@``, indicating udp and tcp respectively
+      (defaults to ``@``, for udp)
+    - ipv4 or ipv6 hostname or address. ipv6 addresses must be in ``[::1]``
+      format, (e.g. ``@[fd00::1]:514``)
+    - optional port number (defaults to ``514``)
+
+This module will provide sane defaults for any part of the remote entry that is
+not specified, so in most cases remote hosts can be specified just using
+``<name>: <address>``.
+
+For backwards compatibility, this module still supports legacy names for the
+config entries. Legacy to new mappings are as follows:
+
+    - ``rsyslog`` -> ``rsyslog/configs``
+    - ``rsyslog_filename`` -> ``rsyslog/config_filename``
+    - ``rsyslog_dir`` -> ``rsyslog/config_dir``
+
+.. note::
+    The legacy config format does not support specifying
+    ``service_reload_command``.
+
+**Internal name:** ``cc_rsyslog``
+
+**Module frequency:** per instance
+
+**Supported distros:** all
+
+**Config keys**::
+
+    rsyslog:
+        config_dir: config_dir
+        config_filename: config_filename
+        configs:
+            - "*.* @@192.158.1.1"
+            - content: "*.*   @@192.0.2.1:10514"
+              filename: 01-example.conf
+            - content: |
+                *.*   @@syslogd.example.com
+        remotes:
+            maas: "192.168.1.1"
+            juju: "10.0.4.1"
+        service_reload_command: [your, syslog, restart, command]
+
+**Legacy config keys**::
+
+    rsyslog:
+        - "*.* @@192.158.1.1"
+    rsyslog_dir: /etc/rsyslog-config.d/
+    rsyslog_filename: 99-local.conf
 """
 
+# Old rsyslog documentation, kept for reference:
+#
+# rsyslog module allows configuration of syslog logging via rsyslog
+# Configuration is done under the cloud-config top level 'rsyslog'.
+#
+# Under 'rsyslog' you can define:
+#   - configs:  [default=[]]
+#     this is a list.  entries in it are a string or a dictionary.
+#     each entry has 2 parts:
+#        * content
+#        * filename
+#     if the entry is a string, then it is assigned to 'content'.
+#     for each entry, content is written to the provided filename.
+#     if filename is not provided, its default is read from 'config_filename'
+#
+#     Content here can be any valid rsyslog configuration.  No format
+#     specific format is enforced.
+#
+#     For simply logging to an existing remote syslog server, via udp:
+#       configs: ["*.* @192.168.1.1"]
+#
+#   - remotes: [default={}]
+#     This is a dictionary of name / value pairs.
+#     In comparison to 'config's, it is more focused in that it only supports
+#     remote syslog configuration.  It is not rsyslog specific, and could
+#     convert to other syslog implementations.
+#
+#     Each entry in remotes is a 'name' and a 'value'.
+#      * name: an string identifying the entry.  good practice would indicate
+#        using a consistent and identifiable string for the producer.
+#        For example, the MAAS service could use 'maas' as the key.
+#      * value consists of the following parts:
+#        * optional filter for log messages
+#          default if not present: *.*
+#        * optional leading '@' or '@@' (indicates udp or tcp respectively).
+#          default if not present (udp): @
+#          This is rsyslog format for that. if not present, is '@'.
+#        * ipv4 or ipv6 or hostname
+#          ipv6 addresses must be in [::1] format. (@[fd00::1]:514)
+#        * optional port
+#          port defaults to 514
+#
+#   - config_filename: [default=20-cloud-config.conf]
+#     this is the file name to use if none is provided in a config entry.
+#
+#   - config_dir: [default=/etc/rsyslog.d]
+#     this directory is used for filenames that are not absolute paths.
+#
+#   - service_reload_command: [default="auto"]
+#     this command is executed if files have been written and thus the syslog
+#     daemon needs to be told.
+#
+# Note, since cloud-init 0.5 a legacy version of rsyslog config has been
+# present and is still supported. See below for the mappings between old
+# value and new value:
+#    old value           -> new value
+#    'rsyslog'           -> rsyslog/configs
+#    'rsyslog_filename'  -> rsyslog/config_filename
+#    'rsyslog_dir'       -> rsyslog/config_dir
+#
+# the legacy config does not support 'service_reload_command'.
+#
+# Example config:
+#   #cloud-config
+#   rsyslog:
+#     configs:
+#       - "*.* @@192.158.1.1"
+#       - content: "*.*   @@192.0.2.1:10514"
+#         filename: 01-example.conf
+#       - content: |
+#         *.*   @@syslogd.example.com
+#     remotes:
+#       maas: "192.168.1.1"
+#       juju: "10.0.4.1"
+#     config_dir: config_dir
+#     config_filename: config_filename
+#     service_reload_command: [your, syslog, restart, command]
+#
+# Example Legacy config:
+#   #cloud-config
+#   rsyslog:
+#     - "*.* @@192.158.1.1"
+#   rsyslog_dir: /etc/rsyslog-config.d/
+#   rsyslog_filename: 99-local.conf
+
 import os
 import re
 import six