Start adding cloud config module docs.

Add the basics of docs that can be extracted from the code itself (also
impose a initial format that will be useful for further modules to
follow). In this initial addition modify the cc_debug.py and
cc_ubuntu_init_switch.py to use this new style.

LP: #1383510

5 files changed, 378 insertions, 18 deletions

diff --git a/ChangeLog b/ChangeLog
index 5e6f6521..0cac0f04 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -3,6 +3,7 @@
  - Digital Ocean: add datasource for Digital Ocean. [Neal Shrader]
  - expose uses_systemd as a distro function (fix rhel7)
  - fix broken 'output' config (LP: #1387340)
+ - begin adding cloud config module docs to config modules (LP: #1383510)
 0.7.6:
  - open 0.7.6
  - Enable vendordata on CloudSigma datasource (LP: #1303986)
diff --git a/cloudinit/config/cc_debug.py b/cloudinit/config/cc_debug.py
index 7219b0f8..a3af4500 100644
--- a/cloudinit/config/cc_debug.py
+++ b/cloudinit/config/cc_debug.py
@@ -14,6 +14,25 @@
 #    You should have received a copy of the GNU General Public License
 #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+"""
+**Summary:** helper to debug cloud-init *internal* datastructures.
+
+**Description:** This module will enable for outputting various internal
+information that cloud-init sources provide to either a file or to the output
+console/log location that this cloud-init has been configured with when
+running.
+
+It can be configured with the following option structure::
+
+    debug:
+       verbose: (defaulting to true)
+       output: (location to write output, defaulting to console + log)
+
+.. note::
+
+    Log configurations are not output.
+"""
+
 from cloudinit import type_utils
 from cloudinit import util
 import copy
@@ -32,6 +51,8 @@ def _make_header(text):
 
 
 def handle(name, cfg, cloud, log, args):
+    """Handler method activated by cloud-init."""
+
     verbose = util.get_cfg_by_path(cfg, ('debug', 'verbose'), default=True)
     if args:
         # if args are provided (from cmdline) then explicitly set verbose
diff --git a/cloudinit/config/cc_ubuntu_init_switch.py b/cloudinit/config/cc_ubuntu_init_switch.py
index 6f994bff..7e88ed85 100644
--- a/cloudinit/config/cc_ubuntu_init_switch.py
+++ b/cloudinit/config/cc_ubuntu_init_switch.py
@@ -17,30 +17,27 @@
 #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """
-ubuntu_init_switch: reboot system into another init
+**Summary:** reboot system into another init.
 
-This provides a way for the user to boot with systemd even if the
-image is set to boot with upstart.  It should be run as one of the first
-cloud_init_modules, and will switch the init system and then issue a reboot.
-The next boot will come up in the target init system and no action will
+**Description:** This module provides a way for the user to boot with systemd
+even if the image is set to boot with upstart.  It should be run as one of the
+first ``cloud_init_modules``, and will switch the init system and then issue a
+reboot. The next boot will come up in the target init system and no action will
 be taken.
 
 This should be inert on non-ubuntu systems, and also exit quickly.
 
-config is comes under the top level 'init_switch' dictionary.
+It can be configured with the following option structure::
 
-#cloud-config
-init_switch:
- target: systemd
- reboot: true
+    init_switch:
+      target: systemd (can be 'systemd' or 'upstart')
+      reboot: true (reboot if a change was made, or false to not reboot)
 
-'target' can be 'systemd' or 'upstart'.  Best effort is made, but its possible
-this system will break, and probably won't interact well with any other
-mechanism you've used to switch the init system.
+.. note::
 
-'reboot': [default=true].
-   true: reboot if a change was made.
-   false: do not reboot.
+    Best effort is made, but it's possible
+    this system will break, and probably won't interact well with any other
+    mechanism you've used to switch the init system.
 """
 
 from cloudinit.settings import PER_INSTANCE
@@ -91,6 +88,7 @@ fi
 
 
 def handle(name, cfg, cloud, log, args):
+    """Handler method activated by cloud-init."""
 
     if not isinstance(cloud.distro, ubuntu.Distro):
         log.debug("%s: distro is '%s', not ubuntu. returning",
diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
index 52a8f92b..9be02766 100644
--- a/doc/rtd/conf.py
+++ b/doc/rtd/conf.py
@@ -27,6 +27,8 @@ project = 'Cloud-Init'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.intersphinx',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
 ]
 
 intersphinx_mapping = {
diff --git a/doc/rtd/topics/modules.rst b/doc/rtd/topics/modules.rst
index d4dd55df..b50acbfa 100644
--- a/doc/rtd/topics/modules.rst
+++ b/doc/rtd/topics/modules.rst
@@ -1,3 +1,341 @@
-=========
+=======
 Modules
-=========
+=======
+
+Apt Configure
+-------------
+
+**Internal name:** ``cc_apt_configure``
+
+.. automodule:: cloudinit.config.cc_apt_configure
+
+Apt Pipelining
+--------------
+
+**Internal name:** ``cc_apt_pipelining``
+
+.. automodule:: cloudinit.config.cc_apt_pipelining
+
+Bootcmd
+-------
+
+**Internal name:** ``cc_bootcmd``
+
+.. automodule:: cloudinit.config.cc_bootcmd
+
+Byobu
+-----
+
+**Internal name:** ``cc_byobu``
+
+.. automodule:: cloudinit.config.cc_byobu
+
+Ca Certs
+--------
+
+**Internal name:** ``cc_ca_certs``
+
+.. automodule:: cloudinit.config.cc_ca_certs
+
+Chef
+----
+
+**Internal name:** ``cc_chef``
+
+.. automodule:: cloudinit.config.cc_chef
+
+Debug
+-----
+
+**Internal name:** ``cc_debug``
+
+.. automodule:: cloudinit.config.cc_debug
+    :members:
+
+Disable Ec2 Metadata
+--------------------
+
+**Internal name:** ``cc_disable_ec2_metadata``
+
+.. automodule:: cloudinit.config.cc_disable_ec2_metadata
+
+Disk Setup
+----------
+
+**Internal name:** ``cc_disk_setup``
+
+.. automodule:: cloudinit.config.cc_disk_setup
+
+Emit Upstart
+------------
+
+**Internal name:** ``cc_emit_upstart``
+
+.. automodule:: cloudinit.config.cc_emit_upstart
+
+Final Message
+-------------
+
+**Internal name:** ``cc_final_message``
+
+.. automodule:: cloudinit.config.cc_final_message
+
+Foo
+---
+
+**Internal name:** ``cc_foo``
+
+.. automodule:: cloudinit.config.cc_foo
+
+Growpart
+--------
+
+**Internal name:** ``cc_growpart``
+
+.. automodule:: cloudinit.config.cc_growpart
+
+Grub Dpkg
+---------
+
+**Internal name:** ``cc_grub_dpkg``
+
+.. automodule:: cloudinit.config.cc_grub_dpkg
+
+Keys To Console
+---------------
+
+**Internal name:** ``cc_keys_to_console``
+
+.. automodule:: cloudinit.config.cc_keys_to_console
+
+Landscape
+---------
+
+**Internal name:** ``cc_landscape``
+
+.. automodule:: cloudinit.config.cc_landscape
+
+Locale
+------
+
+**Internal name:** ``cc_locale``
+
+.. automodule:: cloudinit.config.cc_locale
+
+Mcollective
+-----------
+
+**Internal name:** ``cc_mcollective``
+
+.. automodule:: cloudinit.config.cc_mcollective
+
+Migrator
+--------
+
+**Internal name:** ``cc_migrator``
+
+.. automodule:: cloudinit.config.cc_migrator
+
+Mounts
+------
+
+**Internal name:** ``cc_mounts``
+
+.. automodule:: cloudinit.config.cc_mounts
+
+Package Update Upgrade Install
+------------------------------
+
+**Internal name:** ``cc_package_update_upgrade_install``
+
+.. automodule:: cloudinit.config.cc_package_update_upgrade_install
+
+Phone Home
+----------
+
+**Internal name:** ``cc_phone_home``
+
+.. automodule:: cloudinit.config.cc_phone_home
+
+Power State Change
+------------------
+
+**Internal name:** ``cc_power_state_change``
+
+.. automodule:: cloudinit.config.cc_power_state_change
+
+Puppet
+------
+
+**Internal name:** ``cc_puppet``
+
+.. automodule:: cloudinit.config.cc_puppet
+
+Resizefs
+--------
+
+**Internal name:** ``cc_resizefs``
+
+.. automodule:: cloudinit.config.cc_resizefs
+
+Resolv Conf
+-----------
+
+**Internal name:** ``cc_resolv_conf``
+
+.. automodule:: cloudinit.config.cc_resolv_conf
+
+Rightscale Userdata
+-------------------
+
+**Internal name:** ``cc_rightscale_userdata``
+
+.. automodule:: cloudinit.config.cc_rightscale_userdata
+
+Rsyslog
+-------
+
+**Internal name:** ``cc_rsyslog``
+
+.. automodule:: cloudinit.config.cc_rsyslog
+
+Runcmd
+------
+
+**Internal name:** ``cc_runcmd``
+
+.. automodule:: cloudinit.config.cc_runcmd
+
+Salt Minion
+-----------
+
+**Internal name:** ``cc_salt_minion``
+
+.. automodule:: cloudinit.config.cc_salt_minion
+
+Scripts Per Boot
+----------------
+
+**Internal name:** ``cc_scripts_per_boot``
+
+.. automodule:: cloudinit.config.cc_scripts_per_boot
+
+Scripts Per Instance
+--------------------
+
+**Internal name:** ``cc_scripts_per_instance``
+
+.. automodule:: cloudinit.config.cc_scripts_per_instance
+
+Scripts Per Once
+----------------
+
+**Internal name:** ``cc_scripts_per_once``
+
+.. automodule:: cloudinit.config.cc_scripts_per_once
+
+Scripts User
+------------
+
+**Internal name:** ``cc_scripts_user``
+
+.. automodule:: cloudinit.config.cc_scripts_user
+
+Scripts Vendor
+--------------
+
+**Internal name:** ``cc_scripts_vendor``
+
+.. automodule:: cloudinit.config.cc_scripts_vendor
+
+Seed Random
+-----------
+
+**Internal name:** ``cc_seed_random``
+
+.. automodule:: cloudinit.config.cc_seed_random
+
+Set Hostname
+------------
+
+**Internal name:** ``cc_set_hostname``
+
+.. automodule:: cloudinit.config.cc_set_hostname
+
+Set Passwords
+-------------
+
+**Internal name:** ``cc_set_passwords``
+
+.. automodule:: cloudinit.config.cc_set_passwords
+
+Ssh
+---
+
+**Internal name:** ``cc_ssh``
+
+.. automodule:: cloudinit.config.cc_ssh
+
+Ssh Authkey Fingerprints
+------------------------
+
+**Internal name:** ``cc_ssh_authkey_fingerprints``
+
+.. automodule:: cloudinit.config.cc_ssh_authkey_fingerprints
+
+Ssh Import Id
+-------------
+
+**Internal name:** ``cc_ssh_import_id``
+
+.. automodule:: cloudinit.config.cc_ssh_import_id
+
+Timezone
+--------
+
+**Internal name:** ``cc_timezone``
+
+.. automodule:: cloudinit.config.cc_timezone
+
+Ubuntu Init Switch
+------------------
+
+**Internal name:** ``cc_ubuntu_init_switch``
+
+.. automodule:: cloudinit.config.cc_ubuntu_init_switch
+    :members:
+
+Update Etc Hosts
+----------------
+
+**Internal name:** ``cc_update_etc_hosts``
+
+.. automodule:: cloudinit.config.cc_update_etc_hosts
+
+Update Hostname
+---------------
+
+**Internal name:** ``cc_update_hostname``
+
+.. automodule:: cloudinit.config.cc_update_hostname
+
+Users Groups
+------------
+
+**Internal name:** ``cc_users_groups``
+
+.. automodule:: cloudinit.config.cc_users_groups
+
+Write Files
+-----------
+
+**Internal name:** ``cc_write_files``
+
+.. automodule:: cloudinit.config.cc_write_files
+
+Yum Add Repo
+------------
+
+**Internal name:** ``cc_yum_add_repo``
+
+.. automodule:: cloudinit.config.cc_yum_add_repo