storyboard: add/format docstrings

Also:
+ small docstring fixes in model
+ docstring fixes in log
+ log refactoring
+ other small refactoring
+ some small documentation fixes

1 files changed, 51 insertions, 19 deletions

diff --git a/rumba/log.py b/rumba/log.py
index 67070a6..2ee871c 100644
--- a/rumba/log.py
+++ b/rumba/log.py
@@ -170,7 +170,7 @@ except ImportError:
 
 class RumbaFormatter(logging.Formatter):
     """
-    The logging.Formatter subclass used by Rumba
+    The `logging.Formatter` subclass used by Rumba
     """
 
     level_name_table = {
@@ -178,7 +178,14 @@ class RumbaFormatter(logging.Formatter):
         'ERROR': 'ERR',
         'WARNING': 'WRN',
         'INFO': 'INF',
-        'DEBUG': 'DBG'
+        'DEBUG': 'DBG',
+        # handlers beyond the first will get the
+        # modified levelname
+        'CRT': 'CRT',
+        'ERR': 'ERR',
+        'WRN': 'WRN',
+        'INF': 'INF',
+        'DBG': 'DBG'
     }
 
     def __init__(self):
@@ -202,15 +209,6 @@ def setup():
     logging.getLogger('').setLevel(logging.ERROR)
     logging.getLogger('rumba').setLevel(logging.INFO)
 
-    handler = logging.StreamHandler(sys.stdout)
-    handler.setLevel(logging.DEBUG)
-    formatter = RumbaFormatter()
-    handler.setFormatter(formatter)
-    listener = QueueListener(mq, handler)
-    global logging_listener
-    logging_listener = listener
-    listener.start()
-
 
 # Used for the first call, in order to configure logging
 def _get_logger_with_setup(name):
@@ -231,11 +229,14 @@ _get_logger = _get_logger_with_setup
 
 def get_logger(name):
     """
-    Returns the logger named <name>.
-    <name> should be the module name, for consistency. If setup has not been
-    called yet, it will call it first.
+    Returns the logger named `name`.
+
+    `name` should be the module name, for consistency.
+
+    If setup has not been called yet, it will call it first.
 
     :param name: the name of the desired logger
+    :type name: `str`
     :return: The logger
     """
     return _get_logger(name)
@@ -243,11 +244,13 @@ def get_logger(name):
 
 def set_logging_level(level, name=None):
     """
-    Set the current logging level to <level> for logger named <name>.
-    If name is not specified, sets the logging level for all rumba loggers.
+    Set the current logging level to `level` for the logger named `name`.
+    If `name` is not specified, sets the logging level for all rumba loggers.
 
-    :param level: the desired logging level.
+    :param level: the desired logging level, in string or int form.
+    :type level: `str` or `int`
     :param name: The name of the logger to configure
+    :type name: `str`
 
     .. note:: Accepted levels are:
 
@@ -274,8 +277,8 @@ def set_logging_level(level, name=None):
 
 def reset_logging_level():
     """
-    Resets the current logging levels to the defaults. For Rumba the
-    default is INFO.
+    Resets the current logging level of all loggers to the default.
+    For the Rumba library the default is INFO.
     """
     # Un-sets every logger previously set
     for logger in loggers_set:
@@ -303,6 +306,15 @@ def flush_and_kill_logging():
 
 
 class LogOptions(object):
+    """Class holding the logging configuration"""
+
+    def __init__(self):
+        global logging_listener
+        global mq
+
+        logging_listener = QueueListener(mq)
+        self.log_to_console()
+        logging_listener.start()
 
     @staticmethod
     def _get_handlers():
@@ -316,19 +328,39 @@ class LogOptions(object):
 
     def _add_handler(self, handler):
         handler.setFormatter(RumbaFormatter())
+        handler.setLevel(DEBUG)
         handlers = self._get_handlers() + (handler,)
         self._set_handlers(*handlers)
         return self
 
     def log_to_file(self, path='rumba.log'):
+        """
+        Set the logging framework to log to file on top of the other
+        logging facilities.
+
+        :param path: logging file filename
+        :type path: `str`
+        :return: this `.LogOptions` instance
+        """
         new_handler = logging.handlers.RotatingFileHandler(path)
         return self._add_handler(new_handler)
 
     def reset_logging(self):
+        """
+        Disable all logging facilities
+
+        :return: this `.LogOptions` instance
+        """
         self._set_handlers(*tuple())
         return self
 
     def log_to_console(self):
+        """
+        Set the logging framework to log to stdout on top of the
+        other configured logging facilities
+
+        :return: this `.LogOptions` instance
+        """
         new_handler = logging.StreamHandler(sys.stdout)
         return self._add_handler(new_handler)