From f2a2bfc617f8fe5d97db70bc5b2ccf1b99ec6d4a Mon Sep 17 00:00:00 2001
From: BJ Dierkes <wdierkes@rackspace.com>
Date: Tue, 31 Jul 2012 17:15:08 -0500
Subject: [PATCH] Improving documentation

---
 cement/core/arg.py                      |   5 +-
 cement/core/cache.py                    |   6 +-
 cement/core/config.py                   |   6 +-
 cement/core/controller.py               | 193 +++++-----
 cement/core/exc.py                      |  23 +-
 cement/core/extension.py                |  60 +--
 cement/core/foundation.py               | 491 ++++++++++++------------
 cement/core/log.py                      |   5 +
 cement/core/output.py                   |   5 +
 cement/core/plugin.py                   |   5 +
 doc/source/api/core/arg.rst             |   4 +-
 doc/source/api/core/backend.rst         |   3 +-
 doc/source/api/core/cache.rst           |   4 +-
 doc/source/api/core/config.rst          |   4 +-
 doc/source/api/core/controller.rst      |   4 +-
 doc/source/api/core/exc.rst             |   4 +-
 doc/source/api/core/extension.rst       |   4 +-
 doc/source/api/core/foundation.rst      |   3 +-
 doc/source/api/core/handler.rst         |   4 +-
 doc/source/api/core/hook.rst            |   4 +-
 doc/source/api/core/interface.rst       |   4 +-
 doc/source/api/core/log.rst             |   4 +-
 doc/source/api/core/meta.rst            |   4 +-
 doc/source/api/core/output.rst          |   4 +-
 doc/source/api/core/plugin.rst          |   4 +-
 doc/source/api/ext/ext_argparse.rst     |   2 +
 doc/source/api/ext/ext_configparser.rst |   3 +
 doc/source/api/ext/ext_json.rst         |   4 +-
 doc/source/api/ext/ext_logging.rst      |   4 +-
 doc/source/api/ext/ext_nulloutput.rst   |   2 +
 doc/source/api/ext/ext_plugin.rst       |   2 +
 doc/source/api/utils/fs.rst             |   4 +-
 doc/source/api/utils/misc.rst           |   4 +-
 doc/source/api/utils/shell.rst          |   4 +-
 doc/source/api/utils/test.rst           |   4 +-
 35 files changed, 489 insertions(+), 401 deletions(-)

diff --git a/cement/core/arg.py b/cement/core/arg.py
index fc2ed08d..4c116856 100644
--- a/cement/core/arg.py
+++ b/cement/core/arg.py
@@ -97,7 +97,10 @@ class CementArgumentHandler(handler.CementBaseHandler):
     """
     # pylint: disable=W0232,R0903
     class Meta:
-        """Handler meta-data options."""
+        """
+        Handler meta-data (can be passed as keyword arguments to the parent 
+        class).
+        """
         
         label = None
         """The string identifier of the handler implementation."""
diff --git a/cement/core/cache.py b/cement/core/cache.py
index 455bc923..f3005760 100644
--- a/cement/core/cache.py
+++ b/cement/core/cache.py
@@ -109,7 +109,11 @@ class CementCacheHandler(handler.CementBaseHandler):
 
     """
     class Meta:
-        """Handler meta-data."""
+        """
+        Handler meta-data (can be passed as keyword arguments to the parent 
+        class).
+        """
+        
         label = None
         """String identifier of this handler implementation."""
         
diff --git a/cement/core/config.py b/cement/core/config.py
index 2de72372..7543ed83 100644
--- a/cement/core/config.py
+++ b/cement/core/config.py
@@ -161,6 +161,7 @@ class IConfig(interface.Interface):
         """
         Returns whether or not the section exists.
         
+        :param section: The section to test for.
         :returns: boolean
         
         """
@@ -171,7 +172,10 @@ class CementConfigHandler(handler.CementBaseHandler):
     
     """
     class Meta:
-        """Handler meta-data."""
+        """
+        Handler meta-data (can be passed as keyword arguments to the parent 
+        class).
+        """
         
         label = None
         """The string identifier of the implementation."""
diff --git a/cement/core/controller.py b/cement/core/controller.py
index 73f5fc29..ed1a1316 100644
--- a/cement/core/controller.py
+++ b/cement/core/controller.py
@@ -62,11 +62,16 @@ class IController(interface.Interface):
     """
     # pylint: disable=W0232, C0111, R0903
     class IMeta:
+        """Interface meta-data."""
+        
         label = 'controller'
+        """The string identifier of the interface."""
+        
         validator = controller_validator
+        """The interface validator function."""
     
     # Must be provided by the implementation
-    Meta = interface.Attribute('Handler Meta-data')
+    Meta = interface.Attribute('Handler meta-data')
     
     def _setup(app_obj):
         """
@@ -77,12 +82,8 @@ class IController(interface.Interface):
         Must 'setup' the handler object making it ready for the framework
         or the application to make further calls to it.
         
-        Required Arguments:
-        
-            app_obj
-                The application object.
-                
-        Return: None
+        :param app_obj: The application object.
+        :returns: None
         
         """
     
@@ -96,7 +97,8 @@ class IController(interface.Interface):
         on a controller, as it expects the controller to handle parsing 
         arguments (I.e. self.app.args.parse()).
          
-        Return None       
+        :returns: None       
+        
         """
 
 class expose(object):
@@ -104,16 +106,12 @@ class expose(object):
     Used to expose controller functions to be listed as commands, and to 
     decorate the function with Meta data for the argument parser.
     
-    Optional Arguments:
-    
-        hide
-            Whether the command should be visible.
-        
-        help
-            Help text to display for that command.
-        
-        aliases
-            List of aliases to this command.
+    :param hide: Whether the command should be visible.
+    :type hide: boolean
+    :param help: Help text to display for that command.
+    :type help: str
+    :param aliases: Aliases to this command.
+    :type aliases: list
          
     Usage:
     
@@ -150,59 +148,15 @@ class expose(object):
 
 class CementBaseController(handler.CementBaseHandler):
     """
-    This is an implementation of the IControllerHandler interface, but as a
-    base class that application controllers need to subclass from.  
+    This is an implementation of the 
+    `IControllerHandler <#cement.core.controller.IController>`_ interface, but 
+    as a base class that application controllers `should` subclass from.  
     Registering it directly as a handler is useless.
     
-    NOTE: This handler *requires* that the applications 'arg_handler' be
+    NOTE: This handler **requires** that the applications 'arg_handler' be
     argparse.  If using an alternative argument handler you will need to 
     write your own controller base class.
     
-    Optional / Meta Options:
-    
-        interface
-            The interface that this controller implements (IController).
-            
-        label
-            The label of the controller.  Will be used as the sub-command
-            name for 'stacked' controllers.
-            
-        aliases
-            A list of aliases for the controller.  Will be treated like
-            command/function aliases for non-stacked controllers.  For example:
-            'myapp <controller_label> --help' is the same as 
-            'myapp <controller_alias> --help'.
-            
-            Default: []
-            
-        description
-            The description shown at the top of '--help'.
-            
-        config_section
-            A config [section] to merge config_defaults into.
-            
-            Default: controller.<label>
-            
-        config_defaults
-            Configuration defaults (type: dict) that are merged into the 
-            applications config object for the config_section mentioned above.
-            
-        arguments
-            Arguments to pass to the argument_handler.  The format is a list
-            of tuples whos items are a ( list, dict ).  Meaning:
-            
-                [ ( ['-f', '--foo'], dict(dest='foo', help='foo option') ), ]
-
-        stacked_on
-            A label of another controller to 'stack' commands/arguments on 
-            top of.
-            
-        hide
-            Whether or not to hide the controller entirely.
-            
-        epilog
-            The text that is displayed at the bottom when '--help' is passed.
-    
     Usage:
     
     .. code-block:: python
@@ -216,25 +170,78 @@ class CementBaseController(handler.CementBaseHandler):
                 config_defaults = dict()
                 arguments = []
                 epilog = "This is the text at the bottom of --help."
-        
+                # ...
+                
         class MyStackedController(controller.CementBaseController):
             class Meta:
                 label = 'second_controller'
                 aliases = ['sec', 'secondary']
                 stacked_on = 'base'
+                # ...
                 
     """
     class Meta:
+        """
+        Controller meta-data (can be passed as keyword arguments to the parent 
+        class).
+        
+        """
+        
         interface = IController
-        label = 'base' # provided in subclass
-        aliases = [] # aliases for the controller
+        """The interface this class implements."""
+        
+        label = 'base'
+        """The string identifier for the controller."""
+        
+        aliases = []
+        """
+        A list of aliases for the controller.  Will be treated like
+        command/function aliases for non-stacked controllers.  For example:
+        'myapp <controller_label> --help' is the same as 
+        'myapp <controller_alias> --help'.
+        """
+            
         description = None
-        config_section = None # defaults to controller.<label>
-        config_defaults = {} # default config options
-        arguments = [] # list of tuple (*args, *kwargs)
-        stacked_on = None # controller name to merge commands/options into
-        hide = False # whether to hide controller completely
+        """The description shown at the top of '--help'.  Default: None"""
+        
+        config_section = None
+        """
+        A config [section] to merge config_defaults into.  Cement will default 
+        to controller.<label> if None is set.
+        """
+        
+        config_defaults = {} 
+        """
+        Configuration defaults (type: dict) that are merged into the 
+        applications config object for the config_section mentioned above.
+        """
+        
+        arguments = []
+        """
+        Arguments to pass to the argument_handler.  The format is a list
+        of tuples whos items are a ( list, dict ).  Meaning:
+            
+        ``[ ( ['-f', '--foo'], dict(dest='foo', help='foo option') ), ]``
+        
+        This is equivelant to manually adding each argument to the argument
+        parser:
+        
+        ``parser.add_argument(['-f', '--foo'], help='foo option', dest='foo')``
+        
+        """
+
+        stacked_on = None
+        """
+        A label of another controller to 'stack' commands/arguments on top of.
+        """
+        
+        hide = False
+        """Whether or not to hide the controller entirely."""
+        
         epilog = None
+        """
+        The text that is displayed at the bottom when '--help' is passed.
+        """
         
     ### FIX ME: What is this used for???
     ignored = ['visible', 'hidden', 'exposed']
@@ -253,6 +260,9 @@ class CementBaseController(handler.CementBaseHandler):
         self._arguments = []
         
     def _setup(self, app_obj):
+        """
+        See `IController._setup() <#cement.core.cache.IController._setup>`_.
+        """
         super(CementBaseController, self)._setup(app_obj)
 
         if self._meta.description is None:
@@ -269,7 +279,7 @@ class CementBaseController(handler.CementBaseHandler):
              
     def _parse_args(self):
         """
-        Parse command line arguments and determine a command to dispatch.
+        Parses command line arguments and determine a command to dispatch.
         
         """
         # chop off a command argument if it matches an exposed command
@@ -325,6 +335,8 @@ class CementBaseController(handler.CementBaseHandler):
         This is the default action if no arguments (sub-commands) are passed
         at command line.
         
+        :raises: NotImplementedError
+        
         """
         raise NotImplementedError
     
@@ -340,6 +352,9 @@ class CementBaseController(handler.CementBaseHandler):
     def _collect_from_self(self):
         """
         Collect arguments from this controller.
+        
+        :raises: cement.core.exc.CementRuntimeError
+            
         """
         # collect our Meta arguments
         for _args,_kwargs in self._meta.arguments:
@@ -385,10 +400,8 @@ class CementBaseController(handler.CementBaseHandler):
         """
         Collect arguments from non-stacked controllers.
         
-        Required Arguments:
-        
-            controller
-                The controller to collect arguments from.
+        :param controller: The controller to collect arguments from.
+        :type controller: Uninstantiated controller class
                 
         """
         contr = controller()
@@ -411,10 +424,9 @@ class CementBaseController(handler.CementBaseHandler):
         """
         Collect arguments from stacked controllers.
         
-        Required Arguments:
-        
-            controller
-                The controller to collect arguments from.
+        :param controller: The controller to collect arguments from.
+        :type controller: Uninstantiated controller class
+        :raises: cement.core.exc.CementRuntimeError
                 
         """           
         contr = controller()
@@ -452,10 +464,8 @@ class CementBaseController(handler.CementBaseHandler):
             self.exposed[label] = func_dicts[label]
 
     def _collect_from_controllers(self):
-        """
-        Collect arguments from all controllers.
+        """Collect arguments from all controllers."""
         
-        """
         for controller in handler.list('controller'):
             contr = controller()
             if contr._meta.label == self._meta.label:
@@ -474,6 +484,9 @@ class CementBaseController(handler.CementBaseHandler):
         """
         Collects all commands and arguments from this controller, and other
         availble controllers.
+        
+        :raises: cement.core.exc.CementRuntimeError
+            
         """
         
         LOG.debug("collecting arguments and commands from '%s' controller" % \
@@ -512,10 +525,8 @@ class CementBaseController(handler.CementBaseHandler):
                         
     @property
     def _usage_text(self):
-        """
-        Returns the usage text displayed when '--help' is passed.
+        """Returns the usage text displayed when '--help' is passed."""
         
-        """
         if self == self.app._meta.base_controller:
             txt = "%s <CMD> -opt1 --opt2=VAL [arg1] [arg2] ..." % \
                 self.app.args.prog
@@ -526,10 +537,8 @@ class CementBaseController(handler.CementBaseHandler):
         
     @property
     def _help_text(self):
-        """
-        Returns the help text displayed when '--help' is passed.
+        """Returns the help text displayed when '--help' is passed."""
         
-        """
         cmd_txt = ''
         
         # hack it up to keep commands in alphabetical order
diff --git a/cement/core/exc.py b/cement/core/exc.py
index c47ec317..a0cb7537 100644
--- a/cement/core/exc.py
+++ b/cement/core/exc.py
@@ -1,7 +1,12 @@
 """Cement core exceptions module."""
 
 class CementError(Exception):
-    """Generic errors."""
+    """
+    Generic errors.
+    
+    :param msg: The error message.
+    
+    """
     def __init__(self, msg):
         Exception.__init__(self)
         self.msg = msg
@@ -11,19 +16,33 @@ class CementError(Exception):
 
             
 class CementConfigError(CementError):
+    """Cement configuration related errors."""
     pass
 
 class CementRuntimeError(CementError):
+    """
+    General runtime errors.  Similar to '500 Internal Server Error' in the
+    web world.
+    """
     pass
         
 class CementArgumentError(CementError):
+    """Command line argument related errors."""
     pass
 
 class CementInterfaceError(CementError):
+    """Interface related errors."""
     pass
     
 class CementSignalError(CementError):
-    """Signal errors."""
+    """
+    Signal errors.  For more information regarding signals, reference the 
+    `signal <http://docs.python.org/library/signal.html>`_ library.
+    
+    :param signum: The signal number.
+    :param frame: The signal frame.
+    
+    """
     def __init__(self, signum, frame):
         msg = 'Caught signal %s' % signum
         super(CementSignalError, self).__init__(msg)
diff --git a/cement/core/extension.py b/cement/core/extension.py
index 096c292b..7730fe41 100644
--- a/cement/core/extension.py
+++ b/cement/core/extension.py
@@ -45,8 +45,13 @@ class IExtension(interface.Interface):
     
     # pylint: disable=W0232, C0111, R0903
     class IMeta:
+        """Interface meta-data."""
+        
         label = 'extension'
+        """The string identifier of the interface."""
+        
         validator = extension_validator
+        """The interface validator function."""
     
     # Must be provided by the implementation
     Meta = interface.Attribute('Handler Meta-data class')
@@ -58,12 +63,8 @@ class IExtension(interface.Interface):
         must 'setup' the handler object making it ready for the framework
         or the application to make further calls to it.
         
-        Required Arguments:
-        
-            app_obj
-                The application object. 
-                                
-        Returns: n/a
+        :param app_obj: The application object. 
+        :returns: None
         
         """
     
@@ -72,10 +73,8 @@ class IExtension(interface.Interface):
         Load an extension whose module is 'ext_module'.  For example, 
         'cement.ext.ext_configobj'.
         
-        Required Arguments:
-        
-            ext_module
-                The name of the extension to load.
+        :param ext_module: The name of the extension to load.
+        :type ext_module: str
                 
         """
         
@@ -83,36 +82,42 @@ class IExtension(interface.Interface):
         """
         Load all extensions from ext_list.
         
-        Required Arguments:
-        
-            ext_list
-                A list of extension modules to load.  For example, 
-                ['cement.ext.ext_configobj', 'cement.ext.ext_logging'].
+        :param ext_list: A list of extension modules to load.  For example: 
+            ``['cement.ext.ext_configobj', 'cement.ext.ext_logging']``
+            
+        :type ext_list: list
         
         """
 
 class CementExtensionHandler(handler.CementBaseHandler):
     loaded_extensions = []
+    """A list of loaded extensions."""
     
     class Meta:
+        """
+        Handler meta-data (can be passed as keyword arguments to the parent 
+        class).
+        """
+        
         interface = IExtension
+        """The interface that this class implements."""
+        
         label = 'cement'
+        """The string identifier of the handler."""
         
     def __init__(self, **kw):
         """
-        This is an implementation of the IExtentionHandler interface.  It handles
-        loading framework extensions.
+        This is an implementation of the IExtentionHandler interface.  It 
+        handles loading framework extensions.
     
         """
         super(CementExtensionHandler, self).__init__(**kw)
         self.app = None
         self._loaded_extensions = []
-        
-    def _setup(self, app_obj):
-        self.app = app_obj
     
     @property
     def loaded_extensions(self):
+        """Returns list of loaded extensions."""
         return self._loaded_extensions
         
     def load_extension(self, ext_module):
@@ -120,11 +125,10 @@ class CementExtensionHandler(handler.CementBaseHandler):
         Given an extension module name, load or in other-words 'import' the 
         extension.
         
-        Required Arguments:
-        
-            ext_module
-                The extension module name.  For example 
-                'cement.ext.ext_logging'.
+        :param ext_module: The extension module name.  For example: 
+            'cement.ext.ext_logging'.
+        :type ext_module: str
+        :raises: cement.core.exc.CementRuntimeError
                 
         """
         # If its not a full module path then preppend our default path
@@ -154,10 +158,8 @@ class CementExtensionHandler(handler.CementBaseHandler):
         Given a list of extension modules, iterate over the list and pass
         individually to self.load_extension().
         
-        Required Arguments:
-        
-            ext_list
-                A list of extension modules.
+        :param ext_list: A list of extension modules.
+        :type ext_list: list
                 
         """
         for ext in ext_list:
diff --git a/cement/core/foundation.py b/cement/core/foundation.py
index 7a29b15b..73a6934e 100644
--- a/cement/core/foundation.py
+++ b/cement/core/foundation.py
@@ -1,4 +1,4 @@
-"""Cement core application module."""
+"""Cement core foundation module."""
 
 import re
 import os
@@ -24,6 +24,10 @@ def cement_signal_handler(signum, frame):
     Catch a signal, run the 'signal' hook, and then raise an exception 
     allowing the app to handle logic elsewhere.
     
+    :param signum: The signal number
+    :param frame: The signal frame.
+    :raises: cement.core.exc.CementSignalError
+    
     """      
     LOG.debug('Caught signal %s' % signum)  
     
@@ -36,228 +40,6 @@ class CementApp(meta.MetaMixin):
     """
     The primary class to build applications from.
     
-    Optional / Meta Arguments:
-    
-        label
-            The name of the application.  This should be the common name as
-            you would see and use at the command line.  For example 
-            'helloworld', or 'my-awesome-app'.
-            
-            Default: None
-    
-        bootstrap
-            A bootstrapping module to load after app creation, and before
-            app.setup() is called.  This is useful for larger applications
-            that need to offload their bootstrapping code such as registering
-            hooks/handlers/etc to another file.  
-            
-            This must be a dotted python module path.  
-            I.e. 'myapp.bootstrap' (myapp/bootstrap.py).  Cement will then
-            import the module, and if the module has a 'load()' function, that
-            will also be called.  Essentially, this is the same as an 
-            extension or plugin, but as a facility for the application itself
-            to bootstrap 'hardcoded' application code.  It is also called
-            before plugins are loaded.
-            
-            Default: None
-            
-        debug
-            Toggles debug output.  By default, this setting is also overridden
-            by the '[base] -> debug' config setting parsed in any
-            of the application configuration files (where [base] is the 
-            base configuration section of the application which is determined
-            by Meta.config_section but defaults to Meta.label).
-            
-            Default: False
-            
-        argv
-            A list of arguments to use for parsing command line arguments
-            and options.
-            
-            Default: sys.argv[1:]
-          
-        arguments_override_config
-            A boolean to toggle whether command line arguments should 
-            override configuration values if the argument name matches the
-            config key.  I.e. --foo=bar would override config['myapp']['foo'].
-            
-            Default: False
-            
-        config_section
-            The base configuration section for the application.
-            
-            Default: None
-            
-            Note: Though Meta.config_section defaults to None, Cement will
-            set this to the value of Meta.label (or in other words, the name
-            of the application).
-            
-        config_defaults
-            Default configuration dictionary.  Must be of type 'dict'.
-            
-            Default: None
-            
-        config_files
-            List of config files to parse.  
-            
-            Default: None
-            
-            Note: Though Meta.config_section defaults to None, Cement will
-            set this to a default list based on Meta.label (or in other words, 
-            the name of the application).  This will equate to:
-            
-            ['/etc/<app_label>/<app_label>.conf', '~/.<app_label>.conf', '~/.<app_label>/config']
-            
-        plugins
-            A list of plugins to load.  This is generally considered bad 
-            practice since plugins should be dynamically enabled/disabled
-            via a plugin config file.  
-            
-            Default: []
-        
-        plugin_config_dir
-            A directory path where plugin config files can be found.  Files
-            must end in '.conf'.  By default, this setting is also overridden
-            by the '[base] -> plugin_config_dir' config setting parsed in any
-            of the application configuration files.
-            
-            Default: None
-            
-            Note: Though the meta default is None, Cement will set this to
-            '/etc/<app_label>/plugins.d/' if not set during app.setup().
-        
-        plugin_dir
-            A directory path where plugin code (modules) can be loaded from.
-            By default, this setting is also overridden by the 
-            '[base] -> plugin_dir' config setting parsed in any of the 
-            application configuration files (where [base] is the 
-            base configuration section of the application which is determined
-            by Meta.config_section but defaults to Meta.label).
-            
-            Default: None
-            
-            Note: Though the meta default is None, Cement will set this to
-            '/usr/lib/<app_label>/plugins/' if not set during app.setup()
-        
-        plugin_bootstrap
-            A python package (dotted import path) where plugin code can be
-            loaded from.  This is generally something like 'myapp.plugins'
-            where a plugin file would live at 'myapp/plugins/myplugin.py'.
-            This provides a facility for applications that use 'namespace' 
-            packages allowing plugins to share the applications python
-            namespace.
-            
-            Default: None
-            
-        catch_signals
-            List of signals to catch, and raise exc.CementSignalError for.
-            Can be set to None to disable signal handling.
-
-            Default: [signal.SIGTERM, signal.SIGINT]
-                
-        signal_handler
-            A function that is called to handle any caught signals. 
-            
-            Default: cement.core.foundation.cement_signal_handler
-            
-        config_handler
-            A handler class that implements the IConfig interface.  This can
-            be a string (label of a registered handler), an uninstantiated
-            class, or an instantiated class object.
-
-            Default: cement.ext.ext_configparser.ConfigParserConfigHandler
-            
-        extension_handler
-            A handler class that implements the IExtension interface.  This can
-            be a string (label of a registered handler), an uninstantiated
-            class, or an instantiated class object.
-            
-            Default: cement.core.extension.CementExtensionHandler
-        
-        log_handler
-            A handler class that implements the ILog interface.  This can
-            be a string (label of a registered handler), an uninstantiated
-            class, or an instantiated class object.
-
-            Default: cement.ext.ext_logging.LoggingLogHandler
-            
-        plugin_handler
-            A handler class that implements the IPlugin interface.  This can
-            be a string (label of a registered handler), an uninstantiated
-            class, or an instantiated class object.
-
-            Default: cement.ext.ext_plugin.CementPluginHandler
-        
-        argument_handler
-            A handler class that implements the IArgument interface.  This can
-            be a string (label of a registered handler), an uninstantiated
-            class, or an instantiated class object.
-
-            Default: cement.ext.ext_argparse.ArgParseArgumentHandler
-        
-        output_handler
-            A handler class that implements the IOutput interface.  This can
-            be a string (label of a registered handler), an uninstantiated
-            class, or an instantiated class object.
-
-            Default: cement.ext.ext_nulloutput.NullOutputHandler
-            
-        cache_handler
-            A handler class that implements the ICache interface.  This can
-            be a string (label of a registered handler), an uninstantiated
-            class, or an instantiated class object.
-            
-            Default: None
-            
-        base_controller
-            This is the base application controller.  If a controller is set,
-            runtime operations are passed to the controller for command 
-            dispatch and argument parsing when CementApp.run() is called.
-
-            Default: None
-        
-        core_extensions
-            List of Cement core extensions.  These are generally required by
-            Cement and should only be modified if you know what you're 
-            doing.  Use 'extensions' to add to this list, rather than 
-            overriding core extensions.  That said if you want to prune down
-            your application, you can remove core extensions if they are
-            not necessary (for example if using your own log handler 
-            extension you likely don't want/need LoggingLogHandler to be 
-            registered).
-            
-            Default: ['cement.ext.ext_nulloutput',
-                      'cement.ext.ext_plugin',
-                      'cement.ext.ext_configparser', 
-                      'cement.ext.ext_logging', 
-                      'cement.ext.ext_argparse']
-        
-        extensions
-            List of additional framework extensions to load.
-            
-            Default: []
-        
-        core_meta_override
-            List of meta options that can/will be overridden by config options
-            of the '[base]' config section (where [base] is the base 
-            configuration section of the application which is determined by 
-            Meta.config_section but defaults to Meta.label). These overrides 
-            are required by the framework to function properly and should not 
-            be used by end user (developers) unless you really know what 
-            you're doing.  To add your own extended meta overrides please use 
-            'meta_override'.
-            
-            Default: ['debug', 'plugin_config_dir', 'plugin_dir']
-            
-        meta_override
-            List of meta options that can/will be overridden by config options
-            of the '[base]' config section (where [base] is the 
-            base configuration section of the application which is determined
-            by Meta.config_section but defaults to Meta.label).
-            
-            Default: []
-            
-    
     Usage:
     
     The following is the simplest CementApp:
@@ -301,7 +83,6 @@ class CementApp(meta.MetaMixin):
 
         app = MyApp()
         try:
-            
             app.setup()
             app.run()
         finally:
@@ -309,29 +90,193 @@ class CementApp(meta.MetaMixin):
                 
     """
     class Meta:
+        """
+        Application meta-data (can also be passed as keyword arguments to the 
+        parent class).
+        """
+        
         label = None
+        """
+        The name of the application.  This should be the common name as you 
+        would see and use at the command line.  For example 'helloworld', or 
+        'my-awesome-app'.
+        """
+        
         debug = False
+        """
+        Toggles debug output.  By default, this setting is also overridden
+        by the '[base] -> debug' config setting parsed in any
+        of the application configuration files (where [base] is the 
+        base configuration section of the application which is determined
+        by Meta.config_section but defaults to Meta.label).
+        """
+        
         config_files = None
+        """
+        List of config files to parse.  
+        
+        Note: Though Meta.config_section defaults to None, Cement will
+        set this to a default list based on Meta.label (or in other words, 
+        the name of the application).  This will equate to:
+        
+        .. code-block:: python
+            
+            ['/etc/<app_label>/<app_label>.conf', 
+             '~/.<app_label>.conf', 
+             '~/.<app_label>/config']
+             
+        """
+
         plugins = []
+        """
+        A list of plugins to load.  This is generally considered bad 
+        practice since plugins should be dynamically enabled/disabled
+        via a plugin config file.  
+        """
+        
         plugin_config_dir = None
+        """
+        A directory path where plugin config files can be found.  Files
+        must end in '.conf'.  By default, this setting is also overridden
+        by the '[base] -> plugin_config_dir' config setting parsed in any
+        of the application configuration files.
+        
+        Note: Though the meta default is None, Cement will set this to
+        ``/etc/<app_label>/plugins.d/`` if not set during app.setup().
+        """
+        
         plugin_bootstrap = None
+        """
+        A python package (dotted import path) where plugin code can be
+        loaded from.  This is generally something like 'myapp.plugins'
+        where a plugin file would live at ``myapp/plugins/myplugin.py``.
+        This provides a facility for applications that use 'namespace' 
+        packages allowing plugins to share the applications python
+        namespace.
+        """
+        
         plugin_dir = None
+        """
+        A directory path where plugin code (modules) can be loaded from.
+        By default, this setting is also overridden by the 
+        '[base] -> plugin_dir' config setting parsed in any of the 
+        application configuration files (where [base] is the 
+        base configuration section of the application which is determined
+        by Meta.config_section but defaults to Meta.label).
+
+        Note: Though the meta default is None, Cement will set this to
+        ``/usr/lib/<app_label>/plugins/`` if not set during app.setup()
+        """
+        
         argv = list(sys.argv[1:])
+        """
+        A list of arguments to use for parsing command line arguments
+        and options.
+        """
+        
         arguments_override_config = False
+        """
+        A boolean to toggle whether command line arguments should 
+        override configuration values if the argument name matches the
+        config key.  I.e. --foo=bar would override config['myapp']['foo'].
+        """
+        
         config_section = None
+        """
+        The base configuration section for the application.
+        
+        Note: Though Meta.config_section defaults to None, Cement will
+        set this to the value of Meta.label (or in other words, the name
+        of the application).
+        """
+        
         config_defaults = None
+        """Default configuration dictionary.  Must be of type 'dict'."""
+        
         catch_signals = [signal.SIGTERM, signal.SIGINT]
+        """
+        List of signals to catch, and raise exc.CementSignalError for.
+        Can be set to None to disable signal handling.
+        """
+        
         signal_handler = cement_signal_handler
+        """A function that is called to handle any caught signals."""
+        
         config_handler = ext_configparser.ConfigParserConfigHandler
+        """
+        A handler class that implements the IConfig interface.  This can
+        be a string (label of a registered handler), an uninstantiated
+        class, or an instantiated class object.
+        """
+        
         extension_handler = extension.CementExtensionHandler
+        """
+        A handler class that implements the IExtension interface.  This can
+        be a string (label of a registered handler), an uninstantiated
+        class, or an instantiated class object.
+        """
+        
         log_handler = ext_logging.LoggingLogHandler
+        """
+        A handler class that implements the ILog interface.  This can
+        be a string (label of a registered handler), an uninstantiated
+        class, or an instantiated class object.
+        """
+        
         plugin_handler = ext_plugin.CementPluginHandler
+        """
+        A handler class that implements the IPlugin interface.  This can
+        be a string (label of a registered handler), an uninstantiated
+        class, or an instantiated class object.
+        """
+        
         argument_handler = ext_argparse.ArgParseArgumentHandler
+        """
+        A handler class that implements the IArgument interface.  This can
+        be a string (label of a registered handler), an uninstantiated
+        class, or an instantiated class object.
+        """
+        
         output_handler = ext_nulloutput.NullOutputHandler
+        """
+        A handler class that implements the IOutput interface.  This can
+        be a string (label of a registered handler), an uninstantiated
+        class, or an instantiated class object.
+        """
+        
         cache_handler = None
+        """
+        A handler class that implements the ICache interface.  This can
+        be a string (label of a registered handler), an uninstantiated
+        class, or an instantiated class object.
+        """
+        
         base_controller = None
+        """
+        This is the base application controller.  If a controller is set,
+        runtime operations are passed to the controller for command 
+        dispatch and argument parsing when CementApp.run() is called.
+        """
+        
         extensions = []   
+        """List of additional framework extensions to load."""
+        
         bootstrap = None     
+        """
+        A bootstrapping module to load after app creation, and before
+        app.setup() is called.  This is useful for larger applications
+        that need to offload their bootstrapping code such as registering
+        hooks/handlers/etc to another file.  
+        
+        This must be a dotted python module path.  
+        I.e. 'myapp.bootstrap' (myapp/bootstrap.py).  Cement will then
+        import the module, and if the module has a 'load()' function, that
+        will also be called.  Essentially, this is the same as an 
+        extension or plugin, but as a facility for the application itself
+        to bootstrap 'hardcoded' application code.  It is also called
+        before plugins are loaded.
+        """
+        
         core_extensions = [  
             'cement.ext.ext_nulloutput',
             'cement.ext.ext_plugin',
@@ -339,13 +284,41 @@ class CementApp(meta.MetaMixin):
             'cement.ext.ext_logging', 
             'cement.ext.ext_argparse',
             ]
+        """
+        List of Cement core extensions.  These are generally required by
+        Cement and should only be modified if you know what you're 
+        doing.  Use 'extensions' to add to this list, rather than 
+        overriding core extensions.  That said if you want to prune down
+        your application, you can remove core extensions if they are
+        not necessary (for example if using your own log handler 
+        extension you likely don't want/need LoggingLogHandler to be 
+        registered).
+        """
+        
         core_meta_override = [
             'debug', 
             'plugin_config_dir', 
             'plugin_dir'
             ]
+        """
+        List of meta options that can/will be overridden by config options
+        of the '[base]' config section (where [base] is the base 
+        configuration section of the application which is determined by 
+        Meta.config_section but defaults to Meta.label). These overrides 
+        are required by the framework to function properly and should not 
+        be used by end user (developers) unless you really know what 
+        you're doing.  To add your own extended meta overrides please use 
+        'meta_override'.
+        """
+        
         meta_override = []
-            
+        """
+        List of meta options that can/will be overridden by config options
+        of the '[base]' config section (where [base] is the 
+        base configuration section of the application which is determined
+        by Meta.config_section but defaults to Meta.label).
+        """    
+        
     def __init__(self, label=None, **kw):                
         super(CementApp, self).__init__(**kw)
         
@@ -369,6 +342,7 @@ class CementApp(meta.MetaMixin):
     
     @property
     def argv(self):
+        """The arguments list that will be used when self.run() is called."""
         return self._meta.argv
         
     def extend(self, member_name, member_object):
@@ -378,13 +352,11 @@ class CementApp(meta.MetaMixin):
         extensions to provide functionality that travel along with the 
         application object.
         
-        Required Arguments:
-        
-            member_name
-                The name to attach the object to.
-                
-            member_object
-                The function or class object to attach to CementApp().
+        :param member_name: The name to attach the object to.
+        :type member_name: str
+        :param member_object: The function or class object to attach to 
+            CementApp().
+        :raises: cement.core.exc.CementRuntimeError
                 
         """
         if hasattr(self, member_name):
@@ -416,7 +388,7 @@ class CementApp(meta.MetaMixin):
         executed (possibly letting the developer perform other actions
         before full execution.).
         
-        All handlers should be instantiated and callable after _setup() is
+        All handlers should be instantiated and callable after setup is
         complete.
         
         """
@@ -491,16 +463,9 @@ class CementApp(meta.MetaMixin):
         This is a simple wrapper around self.output.render() which simply
         returns an empty string if no self.output handler is defined.
         
-        Required Arguments:
-        
-            data
-                The data dictionary to render.
-                
-        Optional Arguments:
-        
-            template
-                The template to render to.  Default: None (some output 
-                handlers do not use templates).
+        :param data: The data dictionary to render.
+        :param template: The template to render to.  Default: None (some 
+            output handlers do not use templates).
                 
         """
         for res in hook.run('pre_render', self, data):
@@ -525,22 +490,15 @@ class CementApp(meta.MetaMixin):
         
     @property
     def pargs(self):
-        """
-        A shortcut for self.args.parsed_args.
-        """
+        """A shortcut for self.args.parsed_args."""
         return self.args.parsed_args
      
     def add_arg(self, *args, **kw):
-        """
-        A shortcut for self.args.add_argument.
-        
-        """   
+        """A shortcut for self.args.add_argument."""   
         self.args.add_argument(*args, **kw)
         
     def _lay_cement(self):
-        """
-        Initialize the framework.
-        """
+        """Initialize the framework."""
         LOG.debug("laying cement for the '%s' application" % \
                   self._meta.label)
 
@@ -623,7 +581,13 @@ class CementApp(meta.MetaMixin):
         the handler to load from backend.handlers, or it can be an 
         instantiated or non-instantiated handler class.
         
-        Returns: The instantiated handler object.
+        :param handler_type: The type of handler (aka the interface label)
+        :param hander_def: The handler as defined in CementApp.Meta.
+        :type handler_def: str, uninstantiated object, or instantiated object
+        :param raise_error: Whether or not to raise an exception if unable
+            to resolve the handler.
+        :type raise_error: boolean
+        :returns: The instantiated handler object.
         
         """
         han = None
@@ -777,6 +741,25 @@ class CementApp(meta.MetaMixin):
     def validate_config(self):
         """
         Validate application config settings.
+        
+        Usage:
+        
+        .. code-block:: python
+        
+            import os
+            from cement.core import foundation
+            
+            class MyApp(foundation.CementApp):
+                class Meta:
+                    label = 'myapp'
+                    
+                def validate_config(self):
+                    # test that the log file directory exist, if not create it
+                    logdir = os.path.dirname(self.config.get('log', 'file'))
+
+                    if not os.path.exists(logdir):
+                        os.makedirs(logdir)
+                
         """
         pass
         
diff --git a/cement/core/log.py b/cement/core/log.py
index 068e92ca..5153a318 100644
--- a/cement/core/log.py
+++ b/cement/core/log.py
@@ -144,6 +144,11 @@ class CementLogHandler(handler.CementBaseHandler):
     
     """
     class Meta:
+        """
+        Handler meta-data (can be passed as keyword arguments to the parent 
+        class).
+        """
+        
         interface = ILog
         
     def __init__(self, *args, **kw):
diff --git a/cement/core/output.py b/cement/core/output.py
index c2ccab9d..f27621cb 100644
--- a/cement/core/output.py
+++ b/cement/core/output.py
@@ -82,6 +82,11 @@ class CementOutputHandler(handler.CementBaseHandler):
     
     """
     class Meta:
+        """
+        Handler meta-data (can be passed as keyword arguments to the parent 
+        class).
+        """
+        
         interface = IOutput
         
     def __init__(self, *args, **kw):
diff --git a/cement/core/plugin.py b/cement/core/plugin.py
index 3438c75c..39d3be34 100644
--- a/cement/core/plugin.py
+++ b/cement/core/plugin.py
@@ -93,6 +93,11 @@ class CementPluginHandler(handler.CementBaseHandler):
     """
     
     class Meta:
+        """
+        Handler meta-data (can be passed as keyword arguments to the parent 
+        class).
+        """
+        
         interface = IPlugin
         
     def __init__(self, *args, **kw):
diff --git a/doc/source/api/core/arg.rst b/doc/source/api/core/arg.rst
index 10197651..aba18cbf 100644
--- a/doc/source/api/core/arg.rst
+++ b/doc/source/api/core/arg.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.arg
     :members:
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/backend.rst b/doc/source/api/core/backend.rst
index 812d52b3..9e9a36ed 100644
--- a/doc/source/api/core/backend.rst
+++ b/doc/source/api/core/backend.rst
@@ -5,4 +5,5 @@
 
 .. automodule:: cement.core.backend
     :members:
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/cache.rst b/doc/source/api/core/cache.rst
index 7c47c4ec..a71129a9 100644
--- a/doc/source/api/core/cache.rst
+++ b/doc/source/api/core/cache.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.cache
     :members: 
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/config.rst b/doc/source/api/core/config.rst
index 7a7ba6ad..701edcd0 100644
--- a/doc/source/api/core/config.rst
+++ b/doc/source/api/core/config.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.config
     :members:
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/controller.rst b/doc/source/api/core/controller.rst
index b2ee56a4..686bc6b9 100644
--- a/doc/source/api/core/controller.rst
+++ b/doc/source/api/core/controller.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.controller
     :members:
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/exc.rst b/doc/source/api/core/exc.rst
index 9d290473..18f91ece 100644
--- a/doc/source/api/core/exc.rst
+++ b/doc/source/api/core/exc.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.exc
     :members:   
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/extension.rst b/doc/source/api/core/extension.rst
index fbfd2d0c..32a592c0 100644
--- a/doc/source/api/core/extension.rst
+++ b/doc/source/api/core/extension.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.extension
     :members:    
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/foundation.rst b/doc/source/api/core/foundation.rst
index e1b047ad..274a80ed 100644
--- a/doc/source/api/core/foundation.rst
+++ b/doc/source/api/core/foundation.rst
@@ -5,4 +5,5 @@
 
 .. automodule:: cement.core.foundation
     :members:   
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/handler.rst b/doc/source/api/core/handler.rst
index 129edfa8..e136ab0b 100644
--- a/doc/source/api/core/handler.rst
+++ b/doc/source/api/core/handler.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.handler
     :members:    
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/hook.rst b/doc/source/api/core/hook.rst
index 8bc398de..1969bfe7 100644
--- a/doc/source/api/core/hook.rst
+++ b/doc/source/api/core/hook.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.hook
     :members:   
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/interface.rst b/doc/source/api/core/interface.rst
index 9a9c5d29..e001637b 100644
--- a/doc/source/api/core/interface.rst
+++ b/doc/source/api/core/interface.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.interface
     :members: 
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/log.rst b/doc/source/api/core/log.rst
index 7e8e2495..ea8a37e4 100644
--- a/doc/source/api/core/log.rst
+++ b/doc/source/api/core/log.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.log
     :members:
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/meta.rst b/doc/source/api/core/meta.rst
index 6135c109..b0d38a0c 100644
--- a/doc/source/api/core/meta.rst
+++ b/doc/source/api/core/meta.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.meta
     :members:    
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/output.rst b/doc/source/api/core/output.rst
index fa3cf229..4c078de8 100644
--- a/doc/source/api/core/output.rst
+++ b/doc/source/api/core/output.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.output
     :members:    
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/core/plugin.rst b/doc/source/api/core/plugin.rst
index 9d9e0b7e..8ca874f4 100644
--- a/doc/source/api/core/plugin.rst
+++ b/doc/source/api/core/plugin.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.core.plugin
     :members:   
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/ext/ext_argparse.rst b/doc/source/api/ext/ext_argparse.rst
index 382f8393..fbb0a879 100644
--- a/doc/source/api/ext/ext_argparse.rst
+++ b/doc/source/api/ext/ext_argparse.rst
@@ -6,3 +6,5 @@
 .. automodule:: cement.ext.ext_argparse
     :members:
     :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/ext/ext_configparser.rst b/doc/source/api/ext/ext_configparser.rst
index ed106337..eb28b78b 100644
--- a/doc/source/api/ext/ext_configparser.rst
+++ b/doc/source/api/ext/ext_configparser.rst
@@ -5,3 +5,6 @@
 
 .. automodule:: cement.ext.ext_configparser
     :members:
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/ext/ext_json.rst b/doc/source/api/ext/ext_json.rst
index 77b36b3b..51a4e30b 100644
--- a/doc/source/api/ext/ext_json.rst
+++ b/doc/source/api/ext/ext_json.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.ext.ext_json
     :members:
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/ext/ext_logging.rst b/doc/source/api/ext/ext_logging.rst
index b2cb8b4d..045319c0 100644
--- a/doc/source/api/ext/ext_logging.rst
+++ b/doc/source/api/ext/ext_logging.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.ext.ext_logging
     :members:
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/ext/ext_nulloutput.rst b/doc/source/api/ext/ext_nulloutput.rst
index b99a0fbc..57645871 100644
--- a/doc/source/api/ext/ext_nulloutput.rst
+++ b/doc/source/api/ext/ext_nulloutput.rst
@@ -6,3 +6,5 @@
 .. automodule:: cement.ext.ext_nulloutput
     :members:
     :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/ext/ext_plugin.rst b/doc/source/api/ext/ext_plugin.rst
index 14a610e6..b179e244 100644
--- a/doc/source/api/ext/ext_plugin.rst
+++ b/doc/source/api/ext/ext_plugin.rst
@@ -6,3 +6,5 @@
 .. automodule:: cement.ext.ext_plugin
     :members:
     :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/utils/fs.rst b/doc/source/api/utils/fs.rst
index 3da3a202..dbd2f1d5 100644
--- a/doc/source/api/utils/fs.rst
+++ b/doc/source/api/utils/fs.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.utils.fs
     :members:    
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/utils/misc.rst b/doc/source/api/utils/misc.rst
index 96c316c8..110216a3 100644
--- a/doc/source/api/utils/misc.rst
+++ b/doc/source/api/utils/misc.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.utils.misc
     :members:    
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/utils/shell.rst b/doc/source/api/utils/shell.rst
index f2ef6052..ac9b70ec 100644
--- a/doc/source/api/utils/shell.rst
+++ b/doc/source/api/utils/shell.rst
@@ -5,4 +5,6 @@
 
 .. automodule:: cement.utils.shell
     :members:    
-    :undoc-members:
\ No newline at end of file
+    :undoc-members:
+    :private-members:
+    :show-inheritance:
\ No newline at end of file
diff --git a/doc/source/api/utils/test.rst b/doc/source/api/utils/test.rst
index 08e9800d..680ced62 100644
--- a/doc/source/api/utils/test.rst
+++ b/doc/source/api/utils/test.rst
@@ -6,7 +6,9 @@
 .. automodule:: cement.utils.test
     :members:    
     :undoc-members:
-
+    :private-members:
+    :show-inheritance:
+    
 .. autoclass:: cement.utils.test.raises
 .. autofunction:: cement.utils.test.ok
 .. autofunction:: cement.utils.test.eq