Appease Sphinx

Fixes to docs and DocStrings to silence sphinx warnings and errors
during 'make html':
 - bad indentation in param blocks
 - unsupported section header markup in DocStrings
 - touched docs/source/static (sphinx does not like not having it)
Fixes to DocStrings to make sphinx display paragraphs as intended:
 - .. notes:: not .. 🎶: makes notes show up
 - for reasons undefined sphinx appears to ignore DocStrings in
   __init__; moved the params documentation up to the main class
   DocString.

pecan/configuration.py

@@ -29,16 +29,15 @@ class ConfigDict(dict):
 class Config(object):
     '''
     Base class for Pecan configurations.
+
+    Create a Pecan configuration object from a dictionary or a
+    filename.
+    
+    :param conf_dict: A python dictionary to use for the configuration.
+    :param filename: A filename to use for the configuration.
     '''
 
     def __init__(self, conf_dict={}, filename=''):
-        '''
-        Create a Pecan configuration object from a dictionary or a
-        filename.
-
-        :param conf_dict: A python dictionary to use for the configuration.
-        :param filename: A filename to use for the configuration.
-        '''
 
         self.__values__ = {}
         self.__file__ = filename
@@ -52,7 +51,7 @@ class Config(object):
         Updates this configuration with a dictionary.
 
         :param conf_dict: A python dictionary to update this configuration
-        with.
+                          with.
         '''
 
         if isinstance(conf_dict, dict):
@@ -96,7 +95,7 @@ class Config(object):
         Converts recursively the Config object into a valid dictionary.
 
         :param prefix: A string to optionally prefix all key elements in the
-        returned dictonary.
+                       returned dictonary.
         '''
 
         conf_obj = dict(self)
@@ -186,8 +185,7 @@ def set_config(config, overwrite=False):
     Updates the global configuration.
 
     :param config: Can be a dictionary containing configuration, or a string
-    which
+                   which represents a (relative) configuration filename.
-    represents a (relative) configuration filename.
     '''
 
     if overwrite is True:

pecan/core.py

@@ -49,7 +49,7 @@ def override_template(template, content_type=None):
     your response.
 
     :param template: a valid path to a template file, just as you would specify
-    in an ``@expose``.
+                     in an ``@expose``.
     :param content_type: a valid MIME type to use for the response.func_closure
     '''
 
@@ -86,10 +86,10 @@ def redirect(location=None, internal=False, code=None, headers={},
 
     :param location: The HTTP location to redirect to.
     :param internal: A boolean indicating whether the redirect should be
-    internal.
+                     internal.
     :param code: The HTTP status code to use for the redirect. Defaults to 302.
     :param headers: Any HTTP headers to send with the response, as a
-    dictionary.
+                    dictionary.
     '''
 
     if add_slash:
@@ -123,9 +123,9 @@ def render(template, namespace):
     controller where you have no template specified in the ``@expose``.
 
     :param template: The path to your template, as you would specify in
-    ``@expose``.
+                     ``@expose``.
     :param namespace: The namespace to use for rendering the template, as a
-    dictionary.
+                      dictionary.
     '''
 
     return state.app.render(template, namespace)
@@ -137,8 +137,9 @@ def load_app(config):
     configuration.
 
     :param config: Can be a dictionary containing configuration, or a string
-    which represents a (relative) configuration filename.
+                   which represents a (relative) configuration filename.
-    :returns a pecan.Pecan object
+
+    returns a pecan.Pecan object
     '''
     from configuration import _runtime_conf, set_config
     set_config(config, overwrite=True)
@@ -158,6 +159,22 @@ class Pecan(object):
     '''
     Base Pecan application object. Generally created using ``pecan.make_app``,
     rather than being created manually.
+
+    Creates a Pecan application instance, which is a WSGI application.
+
+    :param root: A string representing a root controller object (e.g.,
+                "myapp.controller.root.RootController")
+    :param default_renderer: The default rendering engine to use. Defaults
+                             to mako.
+    :param template_path: The default relative path to use for templates.
+                          Defaults to 'templates'.
+    :param hooks: A list of Pecan hook objects to use for this application.
+    :param custom_renderers: Custom renderer objects, as a dictionary keyed
+                             by engine name.
+    :param extra_template_vars: Any variables to inject into the template
+                                namespace automatically.
+    :param force_canonical: A boolean indicating if this project should
+                            require canonical URLs.
     '''
 
     def __init__(self, root,
@@ -169,21 +186,6 @@ class Pecan(object):
                  force_canonical=True
         ):
         '''
-        Creates a Pecan application instance, which is a WSGI application.
-
-        :param root: A string representing a root controller object (e.g.,
-                    "myapp.controller.root.RootController")
-        :param default_renderer: The default rendering engine to use. Defaults
-        to mako.
-        :param template_path: The default relative path to use for templates.
-        Defaults to 'templates'.
-        :param hooks: A list of Pecan hook objects to use for this application.
-        :param custom_renderers: Custom renderer objects, as a dictionary keyed
-        by engine name.
-        :param extra_template_vars: Any variables to inject into the template
-        namespace automatically.
-        :param force_canonical: A boolean indicating if this project should
-        require canonical URLs.
         '''
 
         if isinstance(root, basestring):
@@ -254,7 +256,7 @@ class Pecan(object):
         Determines the hooks to be run, in which order.
 
         :param controller: If specified, includes hooks for a specific
-        controller.
+                           controller.
         '''
 
         controller_hooks = []
@@ -272,8 +274,8 @@ class Pecan(object):
         Processes hooks of the specified type.
 
         :param hook_type: The type of hook, including ``before``, ``after``,
-        ``on_error``, and ``on_route``.
+                          ``on_error``, and ``on_route``.
-        :param *args: Arguments to pass to the hooks.
+        :param \*args: Arguments to pass to the hooks.
         '''
 
         if hook_type in ['before', 'on_route']:

pecan/decorators.py

@@ -27,12 +27,12 @@ def expose(template=None,
     access via HTTP, and to configure that access.
 
     :param template: The path to a template, relative to the base template
-    directory.
+                     directory.
     :param content_type: The content-type to use for this template.
-    :param generic: A boolean which flags this as a "generic" controller, which
+    :param generic: A boolean which flags this as a "generic" controller,
-    uses generic functions based upon ``simplegeneric`` generic functions.
+                    which uses generic functions based upon ``simplegeneric``
-    Allows you to split a single controller into multiple paths based upon HTTP
+                    generic functions.  Allows you to split a single
-    method.
+                    controller into multiple paths based upon HTTP method.
     '''
 
     if template == 'json':
@@ -69,7 +69,7 @@ def transactional(ignore_redirects=True):
     regardless of HTTP method.
 
     :param ignore_redirects: Indicates if the hook should ignore redirects
-    for this controller or not.
+                             for this controller or not.
     '''
 
     def deco(f):
@@ -115,7 +115,7 @@ def after_commit(action):
     commit is successfully issued.
 
     :param action: The callable to call after the commit is successfully
-    issued.
+                   issued.
     '''
     return  after_action('commit', action)
 
@@ -127,7 +127,7 @@ def after_rollback(action):
     rollback is successfully issued.
 
     :param action: The callable to call after the rollback is successfully
-    issued.
+                   issued.
     '''
     return  after_action('rollback', action)
 

pecan/hooks.py

@@ -91,6 +91,14 @@ class PecanHook(object):
 
 class TransactionHook(PecanHook):
     '''
+    :param start: A callable that will bind to a writable database and
+                  start a transaction.
+    :param start_ro: A callable that will bind to a readable database.
+    :param commit: A callable that will commit the active transaction.
+    :param rollback: A callable that will roll back the active
+                     transaction.
+    :param clear: A callable that will clear your current context.
+
     A basic framework hook for supporting wrapping requests in
     transactions. By default, it will wrap all but ``GET`` and ``HEAD``
     requests in a transaction. Override the ``is_transactional`` method
@@ -98,15 +106,6 @@ class TransactionHook(PecanHook):
     '''
 
     def __init__(self, start, start_ro, commit, rollback, clear):
-        '''
-        :param start: A callable that will bind to a writable database and
-        start a transaction.
-        :param start_ro: A callable that will bind to a readable database.
-        :param commit: A callable that will commit the active transaction.
-        :param rollback: A callable that will roll back the active
-        transaction.
-        :param clear: A callable that will clear your current context.
-        '''
 
         self.start = start
         self.start_ro = start_ro
@@ -196,6 +195,15 @@ class TransactionHook(PecanHook):
 
 class RequestViewerHook(PecanHook):
     '''
+    :param config:   A (optional) dictionary that can hold ``items`` and/or
+                     ``blacklist`` keys.
+    :param writer:   The stream writer to use. Can redirect output to other
+                     streams as long as the passed in stream has a
+                     ``write`` callable method.
+    :param terminal: Outputs to the chosen stream writer (usually
+                     the terminal)
+    :param headers:  Sets values to the X-HTTP headers
+     
     Returns some information about what is going on in a single request.  It
     accepts specific items to report on but uses a default list of items when
     none are passed in.  Based on the requested ``url``, items can also be
@@ -203,8 +211,8 @@ class RequestViewerHook(PecanHook):
     Configuration is flexible, can be passed in (or not) and can contain
     some or all the keys supported.
 
-    ``items``
+    **items**
-    ---------
+    
     This key holds the items that this hook will display. When this key is
     passed only the items in the list will be used.  Valid items are *any*
     item that the ``request`` object holds, by default it uses the
@@ -217,11 +225,11 @@ class RequestViewerHook(PecanHook):
     * params
     * hooks
 
-    .. :note::
+    .. note::
         This key should always use a ``list`` of items to use.
 
-    ``blacklist``
+    **blacklist**
-    -------------
+    
     This key holds items that will be blacklisted based on ``url``. If
     there is a need to ommit urls that start with `/javascript`, then this
     key would look like::
@@ -232,7 +240,7 @@ class RequestViewerHook(PecanHook):
     will verify that the url is not starting with items in this list to display
     results, otherwise it will get ommited.
 
-    .. :note::
+    .. note::
         This key should always use a ``list`` of items to use.
 
     For more detailed documentation about this hook, please see
@@ -243,16 +251,7 @@ class RequestViewerHook(PecanHook):
 
     def __init__(self, config=None, writer=sys.stdout, terminal=True,
         headers=True):
-        '''
+
-        :param config:   A (optional) dictionary that can hold ``items`` and/or
-                         ``blacklist`` keys.
-        :param writer:   The stream writer to use. Can redirect output to other
-                         streams as long as the passed in stream has a
-                         ``write`` callable method.
-        :param terminal: Outputs to the chosen stream writer (usually
-                         the terminal)
-        :param headers:  Sets values to the X-HTTP headers
-        '''
         if not config:
             self.config = {'items': self.available}
         else: