Merge lp:~raoul-snyman/openlp/docstrings into lp:openlp

[Raoul Snyman]

[Raoul Snyman (raoul-snyman)]

Some more docstrings cleanups.

[Tim Bentley (trb143)]

Looks fine to me.

review: Approve

[lp:~raoul-snyman/openlp/docstrings]

488. By Raoul Snyman on 2009-07-10

Merging from docstrings branch.

=== modified file 'openlp/core/lib/plugin.py'
--- openlp/core/lib/plugin.py	2009-07-06 16:34:13 +0000
+++ openlp/core/lib/plugin.py	2009-07-10 13:16:15 +0000
@@ -31,42 +31,58 @@
     Base class for openlp plugins to inherit from.
 
     Basic attributes are:
-    * name
+
+    ``name``
         The name that should appear in the plugins list.
-    * version
+
+    ``version``
         The version number of this iteration of the plugin.
-    * icon
+
+    ``icon``
         An instance of QIcon, which holds an icon for this plugin.
-    * config
+
+    ``config``
         An instance of PluginConfig, which allows plugins to read and write to
         openlp.org's configuration. This is pre-instantiated.
-    * log
+
+    ``log``
         A log object used to log debugging messages. This is pre-instantiated.
 
     Hook functions:
-    * check_pre_conditions()
+
+    ``check_pre_conditions()``
         Provides the Plugin with a handle to check if it can be loaded.
-    * get_media_manager_item()
+
+    ``get_media_manager_item()``
         Returns an instance of MediaManagerItem to be used in the Media Manager.
-    * add_import_menu_item(import_menu)
+
+    ``add_import_menu_item(import_menu)``
         Add an item to the Import menu.
-    * add_export_menu_item(export_menu)
+
+    ``add_export_menu_item(export_menu)``
         Add an item to the Export menu.
-    * get_settings_tab()
+
+    ``get_settings_tab()``
         Returns an instance of SettingsTabItem to be used in the Settings dialog.
-    * add_to_menu(menubar)
+
+    ``add_to_menu(menubar)``
         A method to add a menu item to anywhere in the menu, given the menu bar.
-    * handle_event(event)
+
+    ``handle_event(event)``
         A method use to handle events, given an Event object.
-    * about()
+
+    ``about()``
         Used in the plugin manager, when a person clicks on the 'About' button.
-    * save(data)
+
+    ``save(data)``
         A method to convert the plugin's data to a string to be stored in the
         Service file.
-    * load(string)
+
+    ``load(string)``
         A method to convert the string from a Service file into the plugin's
         own data format.
-    * render(theme, screen_number)
+
+    ``render(theme, screen_number)``
         A method used to render something to the screen, given the current theme
         and screen number.
     """
@@ -78,11 +94,20 @@
         """
         This is the constructor for the plugin object. This provides an easy
         way for descendent plugins to populate common data. This method *must*
-        be overridden, like so:
-        class MyPlugin(Plugin):
-            def __init__(self):
-                Plugin.__init(self, 'MyPlugin', '0.1')
-                ...
+        be overridden, like so::
+
+            class MyPlugin(Plugin):
+                def __init__(self):
+                    Plugin.__init(self, u'MyPlugin', u'0.1')
+
+        ``name``
+            Defaults to *None*. The name of the plugin.
+
+        ``version``
+            Defaults to *None*. The version of the plugin.
+
+        ``plugin_helpers``
+            Defaults to *None*. A list of helper objects.
         """
         if name is not None:
             self.name = name
@@ -107,50 +132,59 @@
     def check_pre_conditions(self):
         """
         Provides the Plugin with a handle to check if it can be loaded.
+
         Returns True or False.
         """
         return True
 
     def get_media_manager_item(self):
         """
-        Construct a MediaManagerItem object with all the buttons and things you
-        need, and return it for integration into openlp.org.
+        Construct a MediaManagerItem object with all the buttons and things
+        you need, and return it for integration into openlp.org.
         """
         pass
 
     def add_import_menu_item(self, import_menu):
         """
         Create a menu item and add it to the "Import" menu.
+
+        ``import_menu``
+            The Import menu.
         """
         pass
 
     def add_export_menu_item(self, export_menu):
         """
         Create a menu item and add it to the "Export" menu.
+
+        ``export_menu``
+            The Export menu
         """
         pass
 
     def get_settings_tab(self):
         """
-        Create a menu item and add it to the "Import" menu.
+        Create a tab for the settings window.
         """
         pass
 
     def add_to_menu(self, menubar):
         """
         Add menu items to the menu, given the menubar.
+
+        ``menubar``
+            The application's menu bar.
         """
         pass
 
     def handle_event(self, event):
         """
-        Handle the event contained in the event object.
-        """
-    def handle_event(self, event):
-        """
         Handle the event contained in the event object.  If you want
         to use this default behaviour, you must set self.dnd_id equal
         to that sent by the dnd source - eg the MediaItem
+
+        ``event``
+            An object describing the event.
         """
         # default behaviour - can be overridden if desired
         log.debug(u'Handle event called with event %s with payload %s'%(event.event_type, event.payload))
@@ -175,6 +209,9 @@
         """
         Service item data is passed to this function, which should return a
         string which can be written to the service file.
+
+        ``data``
+            The data to be saved.
         """
         pass
 
@@ -182,12 +219,21 @@
         """
         A string from the service file is passed in. This function parses and
         sets up the internals of the plugin.
+
+        ``string``
+            The data to be loaded into the plugin.
         """
         pass
 
     def render(self, theme, screen=None):
         """
         Render the screenth screenful of data using theme settings in theme.
+
+        ``theme``
+            The theme to use when rendering.
+
+        ``screen``
+            Defaults to *None*. The screen to render to.
         """
         pass
 
 
=== modified file 'openlp/core/lib/pluginconfig.py'
--- openlp/core/lib/pluginconfig.py	2009-07-08 05:12:16 +0000
+++ openlp/core/lib/pluginconfig.py	2009-07-10 13:16:15 +0000
@@ -29,28 +29,50 @@
         """
         Initialise the plugin config object, setting the section name to the
         plugin name.
+
+        ``plugin_name``
+            The name of the plugin to use as a section name.
         """
         self.section = plugin_name.lower()
 
     def get_config(self, key, default=None):
         """
         Get a configuration value from the configuration registry.
+
+        ``key``
+            The name of configuration to load.
+
+        ``default``
+            Defaults to *None*. The default value to return if there is no
+            other value.
         """
         return ConfigHelper.get_config(self.section, key, default)
 
     def delete_config(self, key):
         """
         Delete a configuration value from the configuration registry.
+
+        ``key``
+            The name of the configuration to remove.
         """
         return ConfigHelper.delete_config(self.section, key)
 
     def set_config(self, key, value):
         """
         Set a configuration value in the configuration registry.
+
+        ``key``
+            The name of the configuration to save.
+
+        ``value``
+            The value of the configuration to save.
         """
         return ConfigHelper.set_config(self.section, key, value)
 
     def get_data_path(self):
+        """
+        Dynamically build the data file path for a plugin.
+        """
         #app_data = ConfigHelper.get_data_path()
         app_data = ConfigHelper.get_data_path()
         safe_name = self.section.replace(u' ',u'-')
@@ -61,9 +83,21 @@
         return path
 
     def set_data_path(self, path):
+        """
+        Set the data file path.
+
+        ``path``
+            The path to save.
+        """
         return self.set_config(u'data path', os.path.basename(path))
 
     def get_files(self, suffix=None):
+        """
+        Get a list of files from the data files path.
+
+        ``suffix``
+            Defaults to *None*. The extension to search for.
+        """
         try:
             files = os.listdir(self.get_data_path())
         except:
@@ -86,7 +120,10 @@
 
     def load_list(self, name):
         """
-        Load a list from the config file
+        Load a list from the config file.
+
+        ``name``
+            The name of the list.
         """
         list_count = self.get_config(u'%s count' % name)
         if list_count is not None:
@@ -102,7 +139,13 @@
 
     def set_list(self, name, list):
         """
-        Save a list to the config file
+        Save a list to the config file.
+
+        ``name``
+            The name of the list to save.
+
+        ``list``
+            The list of values to save.
         """
         old_count = int(self.get_config(u'%s count' % name, int(0)))
         new_count = len(list)
@@ -116,7 +159,10 @@
 
     def get_last_dir(self, num=None):
         """
-        Read the last directory used for plugin
+        Read the last directory used for plugin.
+
+        ``num``
+            Defaults to *None*. A further qualifier.
         """
         if num is not None:
             name = u'last directory %d' % num
@@ -129,7 +175,10 @@
 
     def set_last_dir(self, directory, num=None):
         """
-        Save the last directory used for plugin
+        Save the last directory used for plugin.
+
+        ``num``
+            Defaults to *None*. A further qualifier.
         """
         if num is not None:
             name = u'last directory %d' % num
 
=== modified file 'openlp/core/lib/pluginmanager.py'
--- openlp/core/lib/pluginmanager.py	2009-07-08 05:12:16 +0000
+++ openlp/core/lib/pluginmanager.py	2009-07-10 13:16:15 +0000
@@ -34,8 +34,11 @@
 
     def __init__(self, dir):
         """
-        The constructor for the plugin manager.
-        Passes the controllers on to the plugins for them to interact with via their ServiceItems
+        The constructor for the plugin manager. Passes the controllers on to
+        the plugins for them to interact with via their ServiceItems.
+
+        ``dir``
+            The directory to search for plugins.
         """
         log.info(u'Plugin manager initing')
         if not dir in sys.path:
@@ -49,7 +52,16 @@
 
     def find_plugins(self, dir, plugin_helpers, eventmanager):
         """
-        Scan the directory dir for objects inheriting from openlp.plugin
+        Scan the directory dir for objects inheriting from ``openlp.plugin``.
+
+        ``dir``
+            The directory to scan.
+
+        ``plugin_helpers``
+            A list of helper objects to pass to the plugins.
+
+        ``eventmanager``
+            The event manager to pass to the plugins.
         """
         self.plugin_helpers = plugin_helpers
         startdepth = len(os.path.abspath(dir).split(os.sep))
@@ -104,8 +116,8 @@
 
     def hook_media_manager(self, mediatoolbox):
         """
-        Loop through all the plugins. If a plugin has a valid media manager item,
-        add it to the media manager.
+        Loop through all the plugins. If a plugin has a valid media manager
+        item, add it to the media manager.
 
         ``mediatoolbox``
             The Media Manager itself.
@@ -118,8 +130,11 @@
 
     def hook_settings_tabs(self, settingsform=None):
         """
-        Loop through all the plugins. If a plugin has a valid settings tab item,
-        add it to the settings tab.
+        Loop through all the plugins. If a plugin has a valid settings tab
+        item, add it to the settings tab.
+
+        ``settingsform``
+            Defaults to *None*. The settings form to add tabs to.
         """
         for plugin in self.plugins:
             settings_tab = plugin.get_settings_tab()
@@ -131,24 +146,30 @@
 
     def hook_import_menu(self, import_menu):
         """
-        Loop through all the plugins and give them an opportunity to add an item
-        to the import menu.
+        Loop through all the plugins and give them an opportunity to add an
+        item to the import menu.
+
+        ``import_menu``
+            The Import menu.
         """
         for plugin in self.plugins:
             plugin.add_import_menu_item(import_menu)
 
     def hook_export_menu(self, export_menu):
         """
-        Loop through all the plugins and give them an opportunity to add an item
-        to the export menu.
+        Loop through all the plugins and give them an opportunity to add an
+        item to the export menu.
+
+        ``export_menu``
+            The Export menu.
         """
         for plugin in self.plugins:
             plugin.add_export_menu_item(export_menu)
 
     def initialise_plugins(self):
         """
-        Loop through all the plugins and give them an opportunity to add an item
-        to the export menu.
+        Loop through all the plugins and give them an opportunity to
+        initialise themselves.
         """
         for plugin in self.plugins:
             plugin.initialise()
 
=== modified file 'openlp/core/lib/renderer.py'
--- openlp/core/lib/renderer.py	2009-06-26 16:17:55 +0000
+++ openlp/core/lib/renderer.py	2009-07-10 13:16:15 +0000
@@ -18,12 +18,12 @@
 Place, Suite 330, Boston, MA 02111-1307 USA
 """
 import logging
-import os,  os.path
+import os
 import sys
 
 from PyQt4 import QtGui, QtCore
 
-class Renderer:
+class Renderer(object):
     """
     Genarates a pixmap image of a array of text. The Text is formatted to
     make sure it fits on the screen and if not extra frames a generated.
@@ -33,6 +33,9 @@
     log.info(u'Renderer Loaded')
 
     def __init__(self):
+        """
+        Initialise the renderer.
+        """
         self._rect = None
         self._debug = 0
         self._right_margin = 64 # the amount of right indent
@@ -47,11 +50,20 @@
         self._bg_frame_small = None
 
     def set_debug(self, debug):
+        """
+        Set the debug mode of the renderer.
+
+        ``debug``
+            The debug mode.
+        """
         self._debug=debug
 
     def set_theme(self, theme):
         """
-        External API to pass in the theme to be used
+        Set the theme to be used.
+
+        ``theme``
+            The theme to be used.
         """
         log.debug(u'set theme')
         self._theme = theme
@@ -64,12 +76,21 @@
                 self.set_bg_image(theme.background_filename)
 
     def set_bg_image(self, filename):
+        """
+        Set a background image.
+
+        ``filename``
+            The name of the image file.
+        """
         log.debug(u'set bg image %s', filename)
         self._bg_image_filename = unicode(filename)
         if self._frame is not None:
             self.scale_bg_image()
 
     def scale_bg_image(self):
+        """
+        Scale the background image to fit the screen.
+        """
         assert self._frame
         preview = QtGui.QImage(self._bg_image_filename)
         width = self._frame.width()
@@ -89,7 +110,16 @@
 
     def set_frame_dest(self, frame_width, frame_height, preview=False):
         """
-        External API to pass the frame size to be painted
+        Set the size of the slide.
+
+        ``frame_width``
+            The width of the slide.
+
+        ``frame_height``
+            The height of the slide.
+
+        ``preview``
+            Defaults to *False*. Whether or not to generate a preview.
         """
         if preview == True:
             self._bg_frame = None
@@ -103,7 +133,14 @@
 
     def format_slide(self, words, footer):
         """
-        External API to sort out the text to pe placed on the frame
+        Figure out how much text can appear on a slide, using the current
+        theme settings.
+
+        ``words``
+            The words to be fitted on the slide.
+
+        ``footer``
+            The footer of the slide.
         """
         log.debug(u'format_slide - Start')
         verses = []
@@ -120,15 +157,28 @@
 
     def set_text_rectangle(self, rect_main, rect_footer):
         """
-        Sets the rectangle within which text should be rendered
+        Sets the rectangle within which text should be rendered.
+
+        ``rect_main``
+            The main text block.
+
+        ``rect_footer``
+            The footer text block.
         """
         self._rect = rect_main
         self._rect_footer = rect_footer
 
     def generate_frame_from_lines(self, lines, footer_lines=None):
         """
-        Render a set of lines according to the theme, return bounding box
-         """
+        Render a set of lines according to the theme, and return the block
+        dimensions.
+
+        ``lines``
+            The lines to be rendered.
+
+        ``footer_lines``
+            Defaults to *None*. The footer to render.
+        """
         log.debug(u'generate_frame_from_lines - Start')
         #print "Render Lines ", lines
         bbox = self._render_lines_unaligned(lines, False)
@@ -139,14 +189,15 @@
         x, y = self._correctAlignment(self._rect, bbox)
         bbox = self._render_lines_unaligned(lines, False,  (x, y), True)
         if footer_lines is not None:
-            bbox = self._render_lines_unaligned(footer_lines, True, (self._rect_footer.left(), self._rect_footer.top()), True )
+            bbox = self._render_lines_unaligned(footer_lines, True,
+                (self._rect_footer.left(), self._rect_footer.top()), True)
         log.debug(u'generate_frame_from_lines - Finish')
         return self._frame
 
     def _generate_background_frame(self):
         """
-        Generate a background frame to the same size as the frame to be used
-        Results cached for performance reasons.
+        Generate a background frame to the same size as the frame to be used.
+        Results are cached for performance reasons.
         """
         assert(self._theme)
         self._bg_frame = QtGui.QImage(self._frame.width(), self._frame.height(),
@@ -196,11 +247,19 @@
 
     def _split_set_of_lines(self, lines, footer):
         """
-        Given a list of lines, decide how to split them best if they don't all fit on the screen
-        - this is done by splitting at 1/2, 1/3 or 1/4 of the set
-        If it doesn't fit, even at this size, just split at each opportunity.
-        We'll do this by getting the bounding box of each line, and then summing them appropriately
-        Returns a list of [lists of lines], one set for each screenful
+        Given a list of lines, decide how to split them best if they don't all
+        fit on the screen. This is done by splitting at 1/2, 1/3 or 1/4 of the
+        set. If it doesn't fit, even at this size, just split at each
+        opportunity. We'll do this by getting the bounding box of each line,
+        and then summing them appropriately.
+
+        Returns a list of [lists of lines], one set for each screenful.
+
+        ``lines``
+            The lines of text to split.
+
+        ``footer``
+            The footer text.
         """
         bboxes = []
         for line in lines:
@@ -254,6 +313,15 @@
         return retval
 
     def _correctAlignment(self, rect, bbox):
+        """
+        Corrects the vertical alignment of text.
+
+        ``rect``
+            The block dimentions.
+
+        ``bbox``
+            Footer dimensions?
+        """
         x = rect.left()
         if int(self._theme.display_verticalAlign) == 0:
             # top align
@@ -268,13 +336,26 @@
             log.error(u'Invalid value for theme.VerticalAlign:%s' % self._theme.display_verticalAlign)
         return x, y
 
-    def _render_lines_unaligned(self, lines,  footer,  tlcorner=(0,0), live=False):
+    def _render_lines_unaligned(self, lines, footer, tlcorner=(0, 0), live=False):
         """
-        Given a list of lines to render, render each one in turn
-        (using the _render_single_line fn - which may result in going
-        off the bottom) They are expected to be pre-arranged to less
-        than a screenful (eg. by using split_set_of_lines)
-        Returns the bounding box of the text as QRect
+        Given a list of lines to render, render each one in turn (using the
+        ``_render_single_line`` fn - which may result in going off the bottom).
+        They are expected to be pre-arranged to less than a screenful (eg. by
+        using split_set_of_lines).
+
+        Returns the bounding box of the text as QRect.
+
+        ``lines``
+            The lines of text to render.
+
+        ``footer``
+            The slide footer.
+
+        ``tlcorner``
+            Defaults to *``(0, 0)``*. Co-ordinates of the top left corner.
+
+        ``live``
+            Defaults to *False*. Whether or not this is a live screen.
         """
         x, y = tlcorner
         brx = x
@@ -282,25 +363,37 @@
         for line in lines:
             # render after current bottom, but at original left edge
             # keep track of right edge to see which is biggest
-            (thisx, bry) = self._render_and_wrap_single_line(line, footer, (x , bry), live)
+            (thisx, bry) = self._render_and_wrap_single_line(line, footer, (x, bry), live)
             if (thisx > brx):
                 brx = thisx
-        retval = QtCore.QRect(x, y,brx-x, bry-y)
+        retval = QtCore.QRect(x, y, brx - x, bry - y)
         if self._debug:
             painter = QtGui.QPainter()
             painter.begin(self._frame)
-            painter.setPen(QtGui.QPen(QtGui.QColor(0,0,255)))
+            painter.setPen(QtGui.QPen(QtGui.QColor(0, 0, 255)))
             painter.drawRect(retval)
             painter.end()
-        return  retval
+        return retval
 
-    def _render_and_wrap_single_line(self, line, footer, tlcorner=(0,0), live=False):
+    def _render_and_wrap_single_line(self, line, footer, tlcorner=(0, 0), live=False):
         """
-        Render a single line of words onto the DC, top left corner
-        specified.
-        If the line is too wide for the context, it wraps, but
-        right-aligns the surplus words in the manner of song lyrics
+        Render a single line of words onto the DC, top left corner specified.
+        If the line is too wide for the context, it wraps, but right-aligns
+        the surplus words in the manner of song lyrics.
+
         Returns the bottom-right corner (of what was rendered) as a tuple(x, y).
+
+        ``line``
+            Line of text to be rendered.
+
+        ``footer``
+            The footer of the slide.
+
+        ``tlcorner``
+            Defaults to *``(0, 0)``*. The top left corner.
+
+        ``live``
+            Defaults to *False*. Whether or not this is a live screen.
         """
         x, y = tlcorner
         # We draw the text to see how big it is and then iterate to make it fit
@@ -397,6 +490,9 @@
         return brcorner
 
     def _set_theme_font(self):
+        """
+        Set the fonts from the current theme settings.
+        """
         self.footerFont = QtGui.QFont(self._theme.font_footer_name,
                      int(self._theme.font_footer_proportion), # size
                      QtGui.QFont.Normal, # weight
@@ -408,11 +504,26 @@
                      0)# italic
         self.mainFont.setPixelSize(int(self._theme.font_main_proportion))
 
-    def _get_extent_and_render(self, line, footer,  tlcorner=(0,0), draw=False, color=None):
+    def _get_extent_and_render(self, line, footer, tlcorner=(0, 0), draw=False, color=None):
         """
-        Find bounding box of text  - as render_single_line.
-        If draw is set, actually draw the text to the current DC as well
-        return width and height of text as a tuple (w,h)
+        Find bounding box of text - as render_single_line. If draw is set,
+        actually draw the text to the current DC as well return width and
+        height of text as a tuple (w, h).
+
+        ``line``
+            The line of text to render.
+
+        ``footer``
+            The footer text.
+
+        ``tlcorner``
+            Defaults to *``(0, 0)``*. The top left corner co-ordinates.
+
+        ``draw``
+            Defaults to *False*. Draw the text to the current surface.
+
+        ``color``
+            Defaults to *None*. The colour to draw with.
         """
         # setup defaults
         painter = QtGui.QPainter()
@@ -424,7 +535,7 @@
         else:
             font = self.mainFont
         painter.setFont(font)
-        if color == None:
+        if color is None:
             if footer:
                 painter.setPen(QtGui.QColor(self._theme.font_footer_color))
             else:
@@ -443,7 +554,13 @@
 
     def snoop_Image(self, image, image2=None):
         """
-        Debugging method to allow images to be viewed
+        Debugging method to allow images to be viewed.
+
+        ``image``
+            An image to save to disk.
+
+        ``image2``
+            Defaults to *None*. Another image to save to disk.
         """
         im = image.toImage()
         im.save(u'renderer.png', u'png')
 
=== modified file 'openlp/core/lib/rendermanager.py'
--- openlp/core/lib/rendermanager.py	2009-07-02 19:04:50 +0000
+++ openlp/core/lib/rendermanager.py	2009-07-10 13:16:15 +0000
@@ -18,26 +18,37 @@
 Place, Suite 330, Boston, MA 02111-1307 USA
 """
 import logging
-import os,  os.path
+import os
 import sys
+import linecache
 
 from PyQt4 import QtGui, QtCore
+
 from renderer import Renderer
 
-import sys
-import linecache
-
-class RenderManager:
+class RenderManager(object):
     """
-    Class to pull all Renderer interactions into one place.
-    The plugins will call helper methods to do the rendering but
-    this class will provide display defense code.
+    Class to pull all Renderer interactions into one place. The plugins will
+    call helper methods to do the rendering but this class will provide
+    display defense code.
     """
     global log
     log=logging.getLogger(u'RenderManager')
     log.info(u'RenderManager Loaded')
 
     def __init__(self, theme_manager, screen_list, screen_number=0):
+        """
+        Initialise the render manager.
+
+        ``theme_manager``
+            The ThemeManager instance, used to get the current theme details.
+
+        ``screen_list``
+            The list of screens available.
+
+        ``screen_number``
+            Defaults to *0*. The index of the output/display screen.
+        """
         log.debug(u'Initilisation started')
         self.screen_list = screen_list
         self.theme_manager = theme_manager
@@ -52,21 +63,46 @@
     def update_display(self, screen_number):
         """
         Updates the render manager's information about the current screen.
+
+        ``screen_number``
+            The updated index of the output/display screen.
         """
         log.debug(u'Update Display')
         if self.current_display != screen_number:
             self.current_display = screen_number
             self.calculate_default(self.screen_list[self.current_display][u'size'])
 
-    def set_global_theme(self, global_theme, global_style = u'Global'):
+    def set_global_theme(self, global_theme, global_style=u'Global'):
+        """
+        Set the global-level theme and the theme level.
+
+        ``global_theme``
+            The global-level theme to be set.
+
+        ``global_style``
+            Defaults to *"Global"*. The theme level, can be "Global",
+            "Service" or "Song".
+        """
         self.global_theme = global_theme
         self.global_style = global_style
 
     def set_service_theme(self, service_theme):
+        """
+        Set the service-level theme.
+
+        ``service_theme``
+            The service-level theme to be set.
+        """
         self.service_theme = service_theme
 
     def set_override_theme(self, theme):
-        log.debug(u'set override theme to %s',  theme)
+        """
+        Set the appropriate theme depending on the theme level.
+
+        ``theme``
+            The name of the song-level theme.
+        """
+        log.debug(u'set override theme to %s', theme)
         if self.global_style == u'Global':
             self.theme = self.global_theme
         elif self.global_style == u'Service':
@@ -84,7 +120,7 @@
                     self.theme = self.service_theme
             else:
                 self.theme = self.global_theme
-        if self.theme is not self.renderer.theme_name:
+        if self.theme != self.renderer.theme_name:
             log.debug(u'theme is now %s',  self.theme)
             self.themedata = self.theme_manager.getThemeData(self.theme)
             self.calculate_default(self.screen_list[self.current_display][u'size'])
@@ -92,7 +128,13 @@
             self.build_text_rectangle(self.themedata)
 
     def build_text_rectangle(self, theme):
-        log.debug(u'build_text_rectangle ')
+        """
+        Builds a text block using the settings in ``theme``.
+
+        ``theme``
+            The theme to build a text block for.
+        """
+        log.debug(u'build_text_rectangle')
         main_rect = None
         footer_rect = None
         if theme.font_main_override == False:
@@ -108,31 +150,52 @@
         self.renderer.set_text_rectangle(main_rect,footer_rect)
 
     def generate_preview(self, themedata):
+        """
+        Generate a preview of a theme.
+
+        ``themedata``
+            The theme to generated a preview for.
+        """
         log.debug(u'generate preview')
         self.calculate_default(QtCore.QSize(1024, 768))
         self.renderer.set_theme(themedata)
         self.build_text_rectangle(themedata)
         self.renderer.set_frame_dest(self.width, self.height, True)
-        lines = []
-        lines.append(u'Amazing Grace!')
-        lines.append(u'How sweet the sound')
-        lines.append(u'To save a wretch like me;')
-        lines.append(u'I once was lost but now am found,')
-        lines.append(u'Was blind, but now I see.')
-        lines1 = []
-        lines1.append(u'Amazing Grace (John Newton)' )
-        lines1.append(u'Public Domain')
-        lines1.append(u'CCLI xxx')
-        return self.renderer.generate_frame_from_lines(lines, lines1)
+        verse = []
+        verse.append(u'Amazing Grace!')
+        verse.append(u'How sweet the sound')
+        verse.append(u'To save a wretch like me;')
+        verse.append(u'I once was lost but now am found,')
+        verse.append(u'Was blind, but now I see.')
+        footer = []
+        footer.append(u'Amazing Grace (John Newton)' )
+        footer.append(u'Public Domain')
+        footer.append(u'CCLI xxx')
+        return self.renderer.generate_frame_from_lines(verse, footer)
 
     def format_slide(self, words):
+        """
+        Calculate how much text can fid on a slide.
+
+        ``words``
+            The words to go on the slides.
+        """
         log.debug(u'format slide')
         self.calculate_default(self.screen_list[self.current_display][u'size'])
         self.build_text_rectangle(self.themedata)
         self.renderer.set_frame_dest(self.width, self.height)
         return self.renderer.format_slide(words, False)
 
-    def generate_slide(self,main_text, footer_text):
+    def generate_slide(self, main_text, footer_text):
+        """
+        Generate the actual slide image.
+
+        ``main_text``
+            The text for the main area of the slide.
+
+        ``footer_text``
+            The text for the slide footer.
+        """
         log.debug(u'generate slide')
         self.calculate_default(self.screen_list[self.current_display][u'size'])
         self.build_text_rectangle(self.themedata)
@@ -140,6 +203,12 @@
         return self.renderer.generate_frame_from_lines(main_text, footer_text)
 
     def resize_image(self, image):
+        """
+        Resize an image to fit on the current screen.
+
+        ``image``
+            The image to resize.
+        """
         preview = QtGui.QImage(image)
         w = self.width
         h = self.height
@@ -154,13 +223,19 @@
         return newImage
 
     def calculate_default(self, screen):
-        log.debug(u'calculate default %s' , screen)
+        """
+        Calculate the default dimentions of the screen.
+
+        ``screen``
+            The QWidget instance of the screen.
+        """
+        log.debug(u'calculate default %s', screen)
         if self.current_display == 0:
             self.width = 1024
             self.height = 768
         else:
             self.width = screen.width()
             self.height = screen.height()
-        log.debug(u'calculate default %d,%d' , self.width, self.height)
+        log.debug(u'calculate default %d, %d', self.width, self.height)
         # 90% is start of footer
         self.footer_start = int(self.height * 0.90)
 
=== modified file 'openlp/core/lib/serviceitem.py'
--- openlp/core/lib/serviceitem.py	2009-06-20 19:11:17 +0000
+++ openlp/core/lib/serviceitem.py	2009-07-10 13:16:15 +0000
@@ -20,10 +20,12 @@
 import logging
 import os
 import time
+
+from PyQt4 import QtCore, QtGui
+
 from openlp.core.lib import buildIcon
-from PyQt4 import QtCore, QtGui
 
-class ServiceItem():
+class ServiceItem(object):
     """
     The service item is a base class for the plugins to use to interact with
     the service manager, the slide controller, and the projection screen
@@ -35,7 +37,10 @@
 
     def __init__(self, hostplugin=None):
         """
-        Init Method
+        Set up the service item.
+
+        ``hostplugin``
+            The plugin that this service item belongs to.
         """
         self.plugin = hostplugin
         if hostplugin is not None:
@@ -56,6 +61,14 @@
         self.service_frames = []
 
     def addIcon(self, icon):
+        """
+        Add an icon to the service item. This is used when displaying the
+        service item in the service manager.
+
+        ``icon``
+            An instance of QIcon or a string to an icon in the resource or on
+            disk.
+        """
         self.icon = icon
         self.iconic_representation = buildIcon(icon)
 
@@ -89,27 +102,63 @@
         else:
             log.error(u'Invalid value renderer :%s' % self.service_item_type)
 
-    def add_from_image(self, path,  frame_title, image):
+    def add_from_image(self, path, frame_title, image):
+        """
+        Add an image slide to the service item.
+
+        ``path``
+            The directory in which the image file is located.
+
+        ``frame_title``
+            A title for the slide in the service item.
+
+        ``image``
+            The actual image file name.
+        """
         self.service_item_type = u'image'
         self.service_item_path = path
         self.service_frames.append({u'title': frame_title, u'image': image})
 
     def add_from_text(self, frame_title, raw_slide):
+        """
+        Add a text slide to the service item.
+
+        ``frame_title``
+            The title of the slide in the service item.
+
+        ``raw_slide``
+            The raw text of the slide.
+        """
         self.service_item_type = u'text'
         frame_title = frame_title.split(u'\n')[0]
         self.service_frames.append({u'title': frame_title, u'raw_slide': raw_slide})
 
     def add_from_command(self, frame_title, command):
+        """
+        Add a slide from a command.
+
+        ``frame_title``
+            The title of the slide in the service item.
+
+        ``command``
+            The command of/for the slide.
+        """
         self.service_item_type = u'command'
         self.service_frames.append({u'title': frame_title, u'command': command})
 
     def get_oos_repr(self):
         """
         This method returns some text which can be saved into the OOS
-        file to represent this item
+        file to represent this item.
         """
-        oos_header = {u'plugin': self.shortname,u'theme':self.theme, u'title':self.title,
-            u'icon':self.icon, u'footer':self.raw_footer, u'type':self.service_item_type}
+        oos_header = {
+            u'plugin': self.shortname,
+            u'theme':self.theme,
+            u'title':self.title,
+            u'icon':self.icon,
+            u'footer':self.raw_footer,
+            u'type':self.service_item_type
+        }
         oos_data = []
         if self.service_item_type == u'text':
             for slide in self.service_frames:
@@ -124,8 +173,14 @@
 
     def set_from_oos(self, serviceitem, path=None):
         """
-        This method takes some oos list (passed from the ServiceManager)
-        and extracts the data actually required
+        This method takes a service item from a saved service file (passed
+        from the ServiceManager) and extracts the data actually required.
+
+        ``serviceitem``
+            The item to extract data from.
+
+        ``path``
+            Defaults to *None*. Any path data, usually for images.
         """
         #print "sfs", serviceitem
         header = serviceitem[u'serviceitem'][u'header']
 
=== modified file 'openlp/core/lib/settingstab.py'
--- openlp/core/lib/settingstab.py	2009-06-05 18:53:50 +0000
+++ openlp/core/lib/settingstab.py	2009-07-10 13:16:15 +0000
@@ -23,11 +23,20 @@
 
 class SettingsTab(QtGui.QWidget):
     """
-    SettingsTab is a helper widget for plugins to define Tabs for the settings dialog.
+    SettingsTab is a helper widget for plugins to define Tabs for the settings
+    dialog.
     """
     def __init__(self, title=None, section=None):
         """
-        Constructor to create the Steetings tab item.
+        Constructor to create the Settings tab item.
+
+        ``title``
+            Defaults to *None*. The title of the tab, which is usually
+            displayed on the tab.
+
+        ``section``
+            Defaults to *None*. This is the section in the configuration file
+            to write to when the ``save`` method is called.
         """
         QtGui.QWidget.__init__(self)
         self.tabTitle = title
@@ -43,6 +52,9 @@
     def setTitle(self, title):
         """
         Set the title of the tab.
+
+        ``title``
+            The title of the tab, which is usually displayed on the tab.
         """
         self.tabTitle = title
 
 
=== modified file 'openlp/core/lib/songxmlhandler.py'
--- openlp/core/lib/songxmlhandler.py	2009-06-21 16:26:33 +0000
+++ openlp/core/lib/songxmlhandler.py	2009-07-10 13:16:15 +0000
@@ -30,21 +30,34 @@
 
 """
 import logging
-from xml.dom.minidom import  Document
+from xml.dom.minidom import Document
 from xml.etree.ElementTree import ElementTree, XML, dump
 
 class SongXMLBuilder():
+    """
+    This class builds the XML used to describe songs.
+    """
     def __init__(self):
+        """
+        Set up the song builder.
+        """
         # Create the minidom document
         self.song_xml = Document()
 
     def new_document(self):
+        """
+        Create a new song XML document.
+        """
         # Create the <song> base element
         self.song = self.song_xml.createElement(u'song')
         self.song_xml.appendChild(self.song)
         self.song.setAttribute(u'version', u'1.0')
 
     def add_lyrics_to_song(self):
+        """
+        Set up and add a ``<lyrics>`` tag which contains the lyrics of the
+        song.
+        """
         # Create the main <lyrics> element
         self.lyrics = self.song_xml.createElement(u'lyrics')
         self.lyrics.setAttribute(u'language', u'en')
@@ -52,50 +65,72 @@
 
     def add_verse_to_lyrics(self, type, number, content):
         """
-        type - type of verse (Chorus, Verse , Bridge, Custom etc
-        number - number of item eg verse 1
-        content - the text to be stored
+        Add a verse to the ``<lyrics>`` tag.
+
+        ``type``
+            A string denoting the type of verse. Possible values are "Chorus",
+            "Verse", "Bridge", and "Custom".
+
+        ``number``
+            An integer denoting the number of the item, for example: verse 1.
+
+        ``content``
+            The actual text of the verse to be stored.
         """
         verse = self.song_xml.createElement(u'verse')
         verse.setAttribute(u'type', type)
         verse.setAttribute(u'label', number)
         self.lyrics.appendChild(verse)
-
-        # add data as a CDATA section
+        # add data as a CDATA section to protect the XML from special chars
         cds = self.song_xml.createCDATASection(content)
         verse.appendChild(cds)
 
     def dump_xml(self):
-        # Debugging aid to see what we have
+        """
+        Debugging aid to dump XML so that we can see what we have.
+        """
         print self.song_xml.toprettyxml(indent=u'  ')
 
     def extract_xml(self):
-        # Print our newly created XML
+        """
+        Extract our newly created XML song.
+        """
         return self.song_xml.toxml(u'utf-8')
 
 class SongXMLParser():
+    """
+    A class to read in and parse a song's XML.
+    """
     global log
     log = logging.getLogger(u'SongXMLParser')
     log.info(u'SongXMLParser Loaded')
 
     def __init__(self, xml):
-        #print xml
+        """
+        Set up our song XML parser.
+
+        ``xml``
+            The XML of the song to be parsed.
+        """
         try:
             self.song_xml = ElementTree(element=XML(xml))
         except:
-            #print "invalid xml ", xml
-            log.debug(u'invalid xml %s', xml)
+            log.debug(u'Invalid xml %s', xml)
 
     def get_verses(self):
-        #return a list of verse's and attributes
-        iter=self.song_xml.getiterator()
+        """
+        Iterates through the verses in the XML and returns a list of verses
+        and their attributes.
+        """
+        iter = self.song_xml.getiterator()
         verse_list = []
         for element in iter:
-            #print element.tag, element.attrib, element.text
             if element.tag == u'verse':
                 verse_list.append([element.attrib, element.text])
         return verse_list
 
     def dump_xml(self):
-        # Debugging aid to see what we have
+        """
+        Debugging aid to dump XML so that we can see what we have.
+        """
         print dump(self.song_xml)
 
=== modified file 'openlp/core/lib/themexmlhandler.py'
--- openlp/core/lib/themexmlhandler.py	2009-07-08 06:55:08 +0000
+++ openlp/core/lib/themexmlhandler.py	2009-07-10 13:16:15 +0000
@@ -345,5 +345,5 @@
         s = u''
         for k in dir(self):
             if k[0:1] != u'_':
-                s += u'%30s : %s\n' %(k, getattr(self, k))
+                s += u'%30s: %s\n' %(k, getattr(self, k))
         return s