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,10 +29,7 @@ class ConfigDict(dict):
 class Config(object):
     '''
     Base class for Pecan configurations.
-    '''
 
-    def __init__(self, conf_dict={}, filename=''):
-        '''
     Create a Pecan configuration object from a dictionary or a
     filename.
     
@@ -40,6 +37,8 @@ class Config(object):
     :param filename: A filename to use for the configuration.
     '''
 
+    def __init__(self, conf_dict={}, filename=''):
+
         self.__values__ = {}
         self.__file__ = filename
         self.update(conf_dict)
@@ -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
-    represents a (relative) configuration filename.
+                   which represents a (relative) configuration filename.
     '''
 
     if overwrite is True:

pecan/core.py

@@ -138,7 +138,8 @@ def load_app(config):
 
     :param config: Can be a dictionary containing configuration, or a string
                    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,17 +159,7 @@ class Pecan(object):
     '''
     Base Pecan application object. Generally created using ``pecan.make_app``,
     rather than being created manually.
-    '''
 
-    def __init__(self, root,
-                 default_renderer='mako',
-                 template_path='templates',
-                 hooks=[],
-                 custom_renderers={},
-                 extra_template_vars={},
-                 force_canonical=True
-        ):
-        '''
     Creates a Pecan application instance, which is a WSGI application.
 
     :param root: A string representing a root controller object (e.g.,
@@ -186,6 +177,17 @@ class Pecan(object):
                             require canonical URLs.
     '''
 
+    def __init__(self, root,
+                 default_renderer='mako',
+                 template_path='templates',
+                 hooks=[],
+                 custom_renderers={},
+                 extra_template_vars={},
+                 force_canonical=True
+        ):
+        '''
+        '''
+
         if isinstance(root, basestring):
             root = self.__translate_root__(root)
 
@@ -273,7 +275,7 @@ class Pecan(object):
 
         :param hook_type: The type of hook, including ``before``, ``after``,
                           ``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

@@ -29,10 +29,10 @@ def expose(template=None,
     :param template: The path to a template, relative to the base template
                      directory.
     :param content_type: The content-type to use for this template.
-    :param generic: A boolean which flags this as a "generic" controller, which
-    uses generic functions based upon ``simplegeneric`` generic functions.
-    Allows you to split a single controller into multiple paths based upon HTTP
-    method.
+    :param generic: A boolean which flags this as a "generic" controller,
+                    which uses generic functions based upon ``simplegeneric``
+                    generic functions.  Allows you to split a single
+                    controller into multiple paths based upon HTTP method.
     '''
 
     if template == 'json':

pecan/hooks.py

@@ -90,14 +90,6 @@ class PecanHook(object):
 
 
 class TransactionHook(PecanHook):
-    '''
-    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
-    to define your own rules for what requests should be transactional.
-    '''
-
-    def __init__(self, start, start_ro, commit, rollback, clear):
     '''
     :param start: A callable that will bind to a writable database and
                   start a transaction.
@@ -106,8 +98,15 @@ class TransactionHook(PecanHook):
     :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
+    to define your own rules for what requests should be transactional.
     '''
 
+    def __init__(self, start, start_ro, commit, rollback, clear):
+
         self.start = start
         self.start_ro = start_ro
         self.commit = commit
@@ -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: