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

2 files changed, 35 insertions, 16 deletions

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",