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

[Raoul Snyman]

[Raoul Snyman (raoul-snyman)]

Some more docstrings!

[Tim Bentley (trb143)]

Approved

review: Approve

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

524. By Raoul Snyman on 2009-09-07

Merged lp:~raoul-snyman/openlp/docstrings into trunk.

=== modified file 'documentation/source/conf.py'
--- documentation/source/conf.py	2009-07-10 15:45:17 +0000
+++ documentation/source/conf.py	2009-09-03 21:41:34 +0000
@@ -47,7 +47,7 @@
 # The short X.Y version.
 version = '2.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.9.0'
+release = '2.0.pre'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -96,7 +96,14 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    'sidebarbgcolor': '#3a60a9',
+    'relbarbgcolor': '#203b6f',
+    'footerbgcolor': '#26437c',
+    'headtextcolor': '#203b6f',
+    'linkcolor': '#26437c',
+    'sidebarlinkcolor': '#ceceff'
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []

=== modified file 'documentation/source/core/index.rst'
--- documentation/source/core/index.rst	2009-07-10 15:45:17 +0000
+++ documentation/source/core/index.rst	2009-09-06 18:59:21 +0000
@@ -3,42 +3,9 @@
 :mod:`core` Module
 ==================
 
-.. automodule:: openlp.core
-   :members:
-
-:mod:`lib` Module
------------------
-
-.. automodule:: openlp.core.lib
-   :members:
-
-:mod:`baselistwithdnd` Submodule
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. automodule:: openlp.core.lib.baselistwithdnd
-   :members:
-
-:mod:`event` Submodule
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. automodule:: openlp.core.lib.event
-   :members:
-
-:mod:`eventmanager` Submodule
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. automodule:: openlp.core.lib.eventmanager
-   :members:
-
-:mod:`eventreceiver` Submodule
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. automodule:: openlp.core.lib.eventreceiver
-   :members:
-
-:mod:`theme` Submodule
-----------------------
-
-.. automodule:: openlp.core.theme
-   :members:
+.. toctree::
+   :maxdepth: 2
+
+   lib
+   theme
 

=== added file 'documentation/source/core/lib.rst'
--- documentation/source/core/lib.rst	1970-01-01 00:00:00 +0000
+++ documentation/source/core/lib.rst	2009-09-06 18:59:21 +0000
@@ -0,0 +1,110 @@
+.. _core-lib:
+
+:mod:`lib` Module
+=================
+
+Module Members
+--------------
+
+.. automodule:: openlp.core.lib
+   :members:
+
+Module Classes
+--------------
+
+:mod:`BaseListWithDnD`
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.baselistwithdnd.BaseListWithDnD
+   :members:
+
+:mod:`EventReceiver`
+^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.eventreceiver.EventReceiver
+   :members:
+
+:mod:`ListWithPreviews`
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.listwithpreviews.ListWithPreviews
+   :members:
+
+:mod:`MediaManagerItem`
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.mediamanageritem.MediaManagerItem
+   :members:
+
+:mod:`Plugin`
+^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.plugin.Plugin
+   :members:
+
+:mod:`PluginConfig`
+^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.pluginconfig.PluginConfig
+   :members:
+
+:mod:`PluginManager`
+^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.pluginmanager.PluginManager
+   :members:
+
+:mod:`Renderer`
+^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.renderer.Renderer
+   :members:
+
+:mod:`RenderManager`
+^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.rendermanager.RenderManager
+   :members:
+
+:mod:`ServiceItem`
+^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.serviceitem.ServiceItem
+   :members:
+
+:mod:`SettingsTab`
+^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.settingstab.SettingsTab
+   :members:
+
+:mod:`SongXMLBuilder`
+^^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.songxmlhandler.SongXMLBuilder
+   :members:
+
+:mod:`SongXMLParser`
+^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.songxmlhandler.SongXMLParser
+   :members:
+
+:mod:`ThemeXML`
+^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.themexmlhandler.ThemeXML
+   :members:
+
+:mod:`OpenLPToolbar`
+^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.toolbar.OpenLPToolbar
+   :members:
+
+:mod:`XmlRootClass`
+^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.core.lib.xmlrootclass.XmlRootClass
+   :members:
+

=== added file 'documentation/source/core/theme.rst'
--- documentation/source/core/theme.rst	1970-01-01 00:00:00 +0000
+++ documentation/source/core/theme.rst	2009-09-03 21:41:34 +0000
@@ -0,0 +1,8 @@
+.. _core-theme:
+
+:mod:`theme` Module
+===================
+
+.. automodule:: openlp.core.theme
+   :members:
+

=== modified file 'documentation/source/index.rst'
--- documentation/source/index.rst	2009-07-10 15:45:17 +0000
+++ documentation/source/index.rst	2009-09-03 21:41:34 +0000
@@ -3,8 +3,12 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to OpenLP's documentation!
-==================================
+Welcome
+=======
+
+Welcome to the OpenLP 2.0 API Documentation! In here you will find all
+information relating to OpenLP's core classes, core plugins, and anything else
+deemed necessary or interesting by the developers.
 
 Contents:
 

=== modified file 'documentation/source/plugins/index.rst'
--- documentation/source/plugins/index.rst	2009-07-10 15:45:17 +0000
+++ documentation/source/plugins/index.rst	2009-09-02 20:42:57 +0000
@@ -6,11 +6,10 @@
 .. automodule:: openlp.plugins
    :members:
 
-:mod:`songs` Plugin
--------------------
+.. toctree::
+   :maxdepth: 2
 
-.. automodule:: openlp.plugins.songs
-   :members:
+   songs
 
 :mod:`bibles` Plugin
 --------------------

=== added file 'documentation/source/plugins/songs.rst'
--- documentation/source/plugins/songs.rst	1970-01-01 00:00:00 +0000
+++ documentation/source/plugins/songs.rst	2009-09-03 21:41:34 +0000
@@ -0,0 +1,46 @@
+.. _plugins-songs:
+
+:mod:`songs` Plugin
+===================
+
+.. automodule:: openlp.plugins.songs
+   :members:
+
+:mod:`SongsPlugin` Class
+------------------------
+
+.. autoclass:: openlp.plugins.songs.songsplugin.SongsPlugin
+   :members:
+
+:mod:`forms` Submodule
+----------------------
+
+.. automodule:: openlp.plugins.songs.forms
+   :members:
+
+:mod:`AuthorsForm`
+^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.plugins.songs.forms.authorsdialog.Ui_AuthorsDialog
+   :members:
+
+.. autoclass:: openlp.plugins.songs.forms.authorsform.AuthorsForm
+   :members:
+
+:mod:`EditSongForm`
+^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.plugins.songs.forms.editsongdialog.Ui_EditSongDialog
+   :members:
+
+.. autoclass:: openlp.plugins.songs.forms.editsongform.EditSongForm
+   :members:
+
+:mod:`EditVerseForm`
+^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openlp.plugins.songs.forms.editversedialog.Ui_EditVerseDialog
+   :members:
+
+.. autoclass:: openlp.plugins.songs.forms.editverseform.EditVerseForm
+   :members:

=== modified file 'openlp.pyw'
--- openlp.pyw	2009-09-01 05:17:32 +0000
+++ openlp.pyw	2009-09-02 20:42:57 +0000
@@ -3,7 +3,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley,
 
 This program is free software; you can redistribute it and/or modify it under
@@ -29,15 +31,7 @@
 from openlp.core.resources import *
 from openlp.core.ui import MainWindow, SplashScreen
 
-filename=u'openlp.log'
 log = logging.getLogger()
-log.setLevel(logging.INFO)
-
-logfile = logging.handlers.RotatingFileHandler(filename ,maxBytes=200000, backupCount=5)
-logfile.setLevel(logging.DEBUG)
-logfile.setFormatter(logging.Formatter(u'%(asctime)s %(name)-15s %(levelname)-8s %(message)s'))
-
-log.addHandler(logfile)
 
 class OpenLP(QtGui.QApplication):
     """
@@ -78,22 +72,40 @@
         self.mainWindow.show()
         # now kill the splashscreen
         self.splash.finish(self.mainWindow)
-        sys.exit(app.exec_())
+        sys.exit(self.exec_())
+
 
 def main():
-    usage = "usage: %prog [options] arg1 arg2"
+    """
+    The main function which parses command line options and then runs
+    the PyQt4 Application.
+    """
+    # Set up command line options.
+    usage = u'Usage: %prog [options] [qt-options]'
     parser = OptionParser(usage=usage)
-    parser.add_option("-d", "--debug",dest="debug",action="store_true",
-                      help="Switch on Debugging ")
+    parser.add_option("-d", "--debug", dest="debug",
+                      action="store_true", help="set logging to DEBUG level")
+    # Set up logging
+    filename = u'openlp.log'
+    logfile = logging.handlers.RotatingFileHandler(
+        filename, maxBytes=200000, backupCount=5)
+    logfile.setFormatter(
+        logging.Formatter(u'%(asctime)s %(name)-15s %(levelname)-8s %(message)s'))
+    log.addHandler(logfile)
+    # Parse command line options and deal with them.
     (options, args) = parser.parse_args()
     if options.debug is not None:
         log.setLevel(logging.DEBUG)
+    else:
+        log.setLevel(logging.INFO)
+    # Now create and actually run the application.
+    app = OpenLP(sys.argv)
+    app.run()
+
 if __name__ == u'__main__':
     """
     Instantiate and run the application.
     """
+    #import cProfile
+    #cProfile.run("main()", "profile.out")
     main()
-    app = OpenLP(sys.argv)
-    #import cProfile
-    #cProfile.run("app.run()", "profile.out")
-    app.run()

=== modified file 'openlp/__init__.py'
--- openlp/__init__.py	2009-05-21 05:15:51 +0000
+++ openlp/__init__.py	2009-09-02 20:42:57 +0000
@@ -1,6 +1,8 @@
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley
 
 This program is free software; you can redistribute it and/or modify it under

=== modified file 'openlp/core/__init__.py'
--- openlp/core/__init__.py	2009-07-09 05:15:26 +0000
+++ openlp/core/__init__.py	2009-09-02 20:42:57 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley
 
 This program is free software; you can redistribute it and/or modify it under

=== modified file 'openlp/core/lib/__init__.py'
--- openlp/core/lib/__init__.py	2009-09-05 01:22:05 +0000
+++ openlp/core/lib/__init__.py	2009-09-06 18:59:21 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley,
 
 This program is free software; you can redistribute it and/or modify it under
@@ -21,17 +23,51 @@
 from PyQt4 import QtCore, QtGui
 
 def translate(context, text):
+    """
+    A special shortcut method to wrap around the Qt4 translation functions.
+    This abstracts the translation procedure so that we can change it if at a
+    later date if necessary, without having to redo the whole of OpenLP.
+
+    ``context``
+        The translation context, used to give each string a context or a
+        namespace.
+
+    ``text``
+        The text to put into the translation tables for translation.
+    """
     return QtGui.QApplication.translate(context, text, None, QtGui.QApplication.UnicodeUTF8)
 
 def file_to_xml(xmlfile):
+    """
+    Open a file and return the contents of the file.
+
+    ``xmlfile``
+        The name of the file.
+    """
     return open(xmlfile).read()
 
 def str_to_bool(stringvalue):
+    """
+    Convert a string version of a boolean into a real boolean.
+
+    ``stringvalue``
+        The string value to examine and convert to a boolean type.
+    """
     if stringvalue is True or stringvalue is False:
         return stringvalue
     return stringvalue.strip().lower() in (u'true', u'yes', u'y')
 
 def buildIcon(icon):
+    """
+    Build a QIcon instance from an existing QIcon, a resource location, or a
+    physical file location. If the icon is a QIcon instance, that icon is
+    simply returned. If not, it builds a QIcon instance from the resource or
+    file name.
+
+    ``icon``
+        The icon to build. This can be a QIcon, a resource string in the form
+        ``:/resource/file.png``, or a file location like ``/path/to/file.png``.
+    """
     ButtonIcon = None
     if type(icon) is QtGui.QIcon:
         ButtonIcon = icon
@@ -59,6 +95,7 @@
     action.setSeparator(True)
     return action
 
+from eventreceiver import Receiver
 from settingsmanager import SettingsManager
 from pluginconfig import PluginConfig
 from plugin import Plugin
@@ -67,12 +104,10 @@
 from mediamanageritem import MediaManagerItem
 from xmlrootclass import XmlRootClass
 from serviceitem import ServiceItem
-from eventreceiver import Receiver
 from serviceitem import ServiceType
 from serviceitem import ServiceItem
 from toolbar import OpenLPToolbar
-from songxmlhandler import SongXMLBuilder
-from songxmlhandler import SongXMLParser
+from songxmlhandler import SongXMLBuilder, SongXMLParser
 from themexmlhandler import ThemeXML
 from renderer import Renderer
 from rendermanager import RenderManager

=== modified file 'openlp/core/lib/eventreceiver.py'
--- openlp/core/lib/eventreceiver.py	2009-09-05 19:58:02 +0000
+++ openlp/core/lib/eventreceiver.py	2009-09-06 18:47:48 +0000
@@ -24,8 +24,9 @@
 
 class EventReceiver(QtCore.QObject):
     """
-    Class to allow events to be passed from different parts of the system.
-    This is a private class and should not be used directly but via the Receiver class
+    Class to allow events to be passed from different parts of the
+    system. This is a private class and should not be used directly
+    but rather via the Receiver class.
 
     ``stop_import``
         Stops the Bible Import
@@ -36,13 +37,13 @@
     ``process_events``
         Requests the Application to flush the events queue
 
-    ``{plugin}_add_service_item ``
+    ``{plugin}_add_service_item``
         ask the plugin to push the selected items to the service item
 
-    ``update_themes ``
+    ``update_themes``
         send out message with new themes
 
-    ``update_global_theme ``
+    ``update_global_theme``
         Tell the components we have a new global theme
 
     ``load_song_list``
@@ -78,31 +79,57 @@
     log = logging.getLogger(u'EventReceiver')
 
     def __init__(self):
+        """
+        Initialise the event receiver, calling the parent constructor.
+        """
         QtCore.QObject.__init__(self)
 
     def send_message(self, event, msg=None):
-        log.debug(u'Event %s passed with payload %s' % (event, msg))
+        """
+        Emit a Qt signal.
+
+        ``event``
+            The event to that was sent.
+
+        ``msg``
+            Defaults to *None*. The message to send with the event.
+        """
         self.emit(QtCore.SIGNAL(event), msg)
 
+
 class Receiver():
     """
-    Class to allow events to be passed from different parts of the system.
-    This is a static wrapper around the EventReceiver class.
-    As there is only one instance of it in the systems the QT signal/slot architecture
-    can send messages across the system
-
-    ``Send message``
-       Receiver().send_message(u'<<Message ID>>', data)
-
-    ``Receive Message``
-        QtCore.QObject.connect(Receiver().get_receiver(),QtCore.SIGNAL(u'<<Message ID>>'),<<ACTION>>)
+    Class to allow events to be passed from different parts of the
+    system. This is a static wrapper around the ``EventReceiver``
+    class. As there is only one instance of it in the system the QT
+    signal/slot architecture can send messages across the system.
+
+    To send a message:
+       ``Receiver().send_message(u'<<Message ID>>', data)``
+
+    To receive a Message
+        ``QtCore.QObject.connect(Receiver().get_receiver(), QtCore.SIGNAL(u'<<Message ID>>'), <<ACTION>>)``
     """
     eventreceiver = EventReceiver()
 
     @staticmethod
     def send_message(event, msg=None):
+        """
+        Sends a message to the messaging system.
+
+        ``event``
+            The event to send.
+
+        ``msg``
+            Defaults to *None*. The message to send with the event.
+        """
         Receiver.eventreceiver.send_message(event, msg)
 
     @staticmethod
     def get_receiver():
+        """
+        Get the global ``eventreceiver`` instance.
+        """
         return Receiver.eventreceiver
+
+

=== modified file 'openlp/core/lib/mediamanageritem.py'
--- openlp/core/lib/mediamanageritem.py	2009-08-31 21:53:35 +0000
+++ openlp/core/lib/mediamanageritem.py	2009-09-06 18:59:21 +0000
@@ -31,28 +31,60 @@
     MediaManagerItem is a helper widget for plugins.
 
     None of the following *need* to be used, feel free to override
-    them cmopletely in your plugin's implementation.  Alternatively, call them from your
-    plugin before or after you've done etra things that you need to.
-
-    The plugin will be assigned an icon called u':/media/media_' + 'self.ShortPluginName + u'image.png'
-     which needs to be available in the main resources in order for them to work, you need to have setup
-
-     self.TranslationContext
-     self.PluginTextShort # eg 'Image' for the image plugin
-     self.ConfigSection - where the items in the media manager are stored
-       this could potentially be self.PluginTextShort.lower()
-
-     self.OnNewPrompt=u'Select Image(s)'
-     self.OnNewFileMasks=u'Images (*.jpg *jpeg *.gif *.png *.bmp)'
-       assumes that the new action is to load a file. If not, override onnew
-
-     self.ListViewWithDnD_class - there is a base list class with DnD assigned to it (openlp.core.lib.BaseListWithDnD())
-     each plugin needs to inherit a class from this and pass that *class* (not an instance) to here
-     via the ListViewWithDnD_class member
-
-     self.PreviewFunction - a function which returns a QImage to represent the item (a preview usually)
-        - no scaling required - that's done later
-        If this fn is not defined, a default will be used (treat the filename as an image)
+    them cmopletely in your plugin's implementation. Alternatively,
+    call them from your plugin before or after you've done extra
+    things that you need to.
+
+    **Constructor Parameters**
+
+    ``parent``
+        The parent widget. Usually this will be the *Media Manager*
+        itself. This needs to be a class descended from ``QWidget``.
+
+    ``icon``
+        Either a ``QIcon``, a resource path, or a file name. This is
+        the icon which is displayed in the *Media Manager*.
+
+    ``title``
+        The title visible on the item in the *Media Manager*.
+
+    **Member Variables**
+
+    When creating a descendant class from this class for your plugin,
+    the following member variables should be set.
+
+    ``self.TranslationContext``
+        This sets the translation context of all the text in the
+        Media Manager item.
+
+    ``self.PluginTextShort``
+        The shortened name for the plugin, e.g. *'Image'* for the
+        image plugin.
+
+     ``self.ConfigSection``
+        The section in the configuration where the items in the media
+        manager are stored. This could potentially be
+        ``self.PluginTextShort.lower()``.
+
+     ``self.OnNewPrompt``
+        Defaults to *'Select Image(s)'*.
+
+     ``self.OnNewFileMasks``
+        Defaults to *'Images (*.jpg *jpeg *.gif *.png *.bmp)'*. This
+        assumes that the new action is to load a file. If not, you
+        need to override the ``OnNew`` method.
+
+     ``self.ListViewWithDnD_class``
+        This must be a **class**, not an object, descended from
+        ``openlp.core.lib.BaseListWithDnD`` that is not used in any
+        other part of OpenLP.
+
+     ``self.PreviewFunction``
+        This must be a method which returns a QImage to represent the
+        item (usually a preview). No scaling is required, that is
+        performed automatically by OpenLP when necessary. If this
+        method is not defined, a default will be used (treat the
+        filename as an image).
     """
 
     global log
@@ -83,12 +115,17 @@
         self.initialise()
 
     def retranslateUi(self):
+        """
+        This method is called automatically to provide OpenLP with the
+        opportunity to translate the ``MediaManagerItem`` to another
+        language.
+        """
         pass
 
     def addToolbar(self):
         """
-        A method to help developers easily add a toolbar to the media manager
-        item.
+        A method to help developers easily add a toolbar to the media
+        manager item.
         """
         if self.Toolbar is None:
             self.Toolbar = OpenLPToolbar(self)
@@ -97,9 +134,29 @@
     def addToolbarButton(self, title, tooltip, icon, slot=None, objectname=None):
         """
         A method to help developers easily add a button to the toolbar.
+
+        ``title``
+            The title of the button.
+
+        ``tooltip``
+            The tooltip to be displayed when the mouse hovers over the
+            button.
+
+        ``icon``
+            The icon of the button. This can be an instance of QIcon, or a
+            string cotaining either the absolute path to the image, or an
+            internal resource path starting with ':/'.
+
+        ``slot``
+            The method to call when the button is clicked.
+
+        ``objectname``
+            The name of the button.
         """
-        # NB different order (when I broke this out, I wanted to not break compatability)
-        # but it makes sense for the icon to come before the tooltip (as you have to have an icon, but not neccesarily a tooltip)
+        # NB different order (when I broke this out, I didn't want to
+        # break compatability), but it makes sense for the icon to
+        # come before the tooltip (as you have to have an icon, but
+        # not neccesarily a tooltip)
         self.Toolbar.addToolbarButton(title, icon, tooltip, slot, objectname)
 
     def addToolbarSeparator(self):
@@ -109,6 +166,11 @@
         self.Toolbar.addSeparator()
 
     def setupUi(self):
+        """
+        This method sets up the interface on the button. Plugin
+        developers use this to add and create toolbars, and the rest
+        of the interface of the media manager item.
+        """
         # Add a toolbar
         self.addToolbar()
         # Create buttons for the toolbar
@@ -189,6 +251,11 @@
            QtCore.SIGNAL(u'doubleClicked(QModelIndex)'), self.onPreviewClick)
 
     def initialise(self):
+        """
+        Implement this method in your descendent media manager item to
+        do any UI or other initialisation. This method is called
+        automatically.
+        """
         pass
 
     def addHeaderBar(self):

=== modified file 'openlp/core/lib/plugin.py'
--- openlp/core/lib/plugin.py	2009-08-26 05:00:19 +0000
+++ openlp/core/lib/plugin.py	2009-09-06 18:59:21 +0000
@@ -21,17 +21,13 @@
 import logging
 from PyQt4 import QtCore
 
-from openlp.core.lib import PluginConfig
-# why does this not work???
-# from openlp.core.lib import Event,  EventType
-# so I have to do this???
-from eventreceiver import Receiver
+from openlp.core.lib import PluginConfig, Receiver
 
 class Plugin(object):
     """
     Base class for openlp plugins to inherit from.
 
-    Basic attributes are:
+    **Basic Attributes**
 
     ``name``
         The name that should appear in the plugins list.
@@ -49,7 +45,7 @@
     ``log``
         A log object used to log debugging messages. This is pre-instantiated.
 
-    Hook functions:
+    **Hook Functions**
 
     ``check_pre_conditions()``
         Provides the Plugin with a handle to check if it can be loaded.
@@ -201,7 +197,7 @@
 
     def finalise(self):
         """
-        Called by the plugin Manager to cleanup things
+        Called by the plugin Manager to cleanup things.
         """
         pass
 

=== modified file 'openlp/core/lib/pluginconfig.py'
--- openlp/core/lib/pluginconfig.py	2009-09-02 01:44:09 +0000
+++ openlp/core/lib/pluginconfig.py	2009-09-06 18:59:21 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008 -2009 Martin Thompson, Tim Bentley
 
 This program is free software; you can redistribute it and/or modify it under
@@ -19,6 +21,7 @@
 """
 
 import os
+
 from openlp.core.utils import ConfigHelper
 
 class PluginConfig(object):

=== modified file 'openlp/core/lib/pluginmanager.py'
--- openlp/core/lib/pluginmanager.py	2009-09-05 08:52:01 +0000
+++ openlp/core/lib/pluginmanager.py	2009-09-06 18:59:21 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008 - 2009 Martin Thompson, Tim Bentley,
 
 This program is free software; you can redistribute it and/or modify it under
@@ -52,7 +54,8 @@
 
     def find_plugins(self, dir, plugin_helpers):
         """
-        Scan the directory dir for objects inheriting from ``openlp.plugin``.
+        Scan the directory ``dir`` for objects inheriting from the ``Plugin``
+        class.
 
         ``dir``
             The directory to scan.

=== modified file 'openlp/core/lib/renderer.py'
--- openlp/core/lib/renderer.py	2009-09-03 17:46:46 +0000
+++ openlp/core/lib/renderer.py	2009-09-06 18:59:21 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley
 
 This program is free software; you can redistribute it and/or modify it under

=== modified file 'openlp/core/lib/rendermanager.py'
--- openlp/core/lib/rendermanager.py	2009-09-03 17:46:46 +0000
+++ openlp/core/lib/rendermanager.py	2009-09-06 18:59:21 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008 - 2009Martin Thompson, Tim Bentley
 
 This program is free software; you can redistribute it and/or modify it under
@@ -31,23 +33,23 @@
     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.
+
+    ``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.
     """
     global log
-    log=logging.getLogger(u'RenderManager')
+    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

=== modified file 'openlp/core/lib/serviceitem.py'
--- openlp/core/lib/serviceitem.py	2009-09-05 13:30:09 +0000
+++ openlp/core/lib/serviceitem.py	2009-09-06 18:59:21 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley
 
 This program is free software; you can redistribute it and/or modify it under
@@ -37,7 +39,7 @@
     compositor.
     """
     global log
-    log=logging.getLogger(u'ServiceItem')
+    log = logging.getLogger(u'ServiceItem')
     log.info(u'Service Item created')
 
     def __init__(self, hostplugin=None):

=== modified file 'openlp/core/lib/settingsmanager.py'
--- openlp/core/lib/settingsmanager.py	2009-09-06 12:13:09 +0000
+++ openlp/core/lib/settingsmanager.py	2009-09-06 18:59:21 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley
 
 This program is free software; you can redistribute it and/or modify it under
@@ -20,8 +22,9 @@
 
 class SettingsManager(object):
     """
-    Class to control the size of the UI components so they size correctly
-    This class is created by the main window and then calculates the size of individual components
+    Class to control the size of the UI components so they size correctly.
+    This class is created by the main window and then calculates the size of
+    individual components.
     """
     def __init__(self, screen):
         self.screen = screen[0]

=== modified file 'openlp/core/lib/settingstab.py'
--- openlp/core/lib/settingstab.py	2009-08-29 07:17:56 +0000
+++ openlp/core/lib/settingstab.py	2009-09-06 18:59:21 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008 Martin Thompson, Tim Bentley
 
 This program is free software; you can redistribute it and/or modify it under
@@ -19,6 +21,7 @@
 """
 
 from PyQt4 import QtCore, QtGui
+
 from openlp.core.lib import PluginConfig
 
 class SettingsTab(QtGui.QWidget):

=== modified file 'openlp/core/lib/songxmlhandler.py'
--- openlp/core/lib/songxmlhandler.py	2009-07-10 13:16:15 +0000
+++ openlp/core/lib/songxmlhandler.py	2009-07-14 13:51:27 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley, Carsten Tinggaard
 
 This program is free software; you can redistribute it and/or modify it under
@@ -16,26 +18,25 @@
 You should have received a copy of the GNU General Public License along with
 this program; if not, write to the Free Software Foundation, Inc., 59 Temple
 Place, Suite 330, Boston, MA 02111-1307 USA
-from xml.dom.minidom import  Document
-from xml.etree.ElementTree import ElementTree, XML, dump
-
-<?xml version="1.0" encoding="UTF-8"?>
-<song version="1.0">
-   <lyrics language="en">
-       <verse type="chorus" label="1">
-           <![CDATA[ ... ]]>
-       </verse>
-   </lyrics>
-</song>
-
 """
 import logging
 from xml.dom.minidom import Document
 from xml.etree.ElementTree import ElementTree, XML, dump
 
-class SongXMLBuilder():
+class SongXMLBuilder(object):
     """
     This class builds the XML used to describe songs.
+
+    The basic XML looks like this::
+
+        <?xml version="1.0" encoding="UTF-8"?>
+        <song version="1.0">
+          <lyrics language="en">
+            <verse type="chorus" label="1">
+              <![CDATA[ ... ]]>
+            </verse>
+          </lyrics>
+        </song>
     """
     def __init__(self):
         """
@@ -97,9 +98,21 @@
         """
         return self.song_xml.toxml(u'utf-8')
 
-class SongXMLParser():
+
+class SongXMLParser(object):
     """
     A class to read in and parse a song's XML.
+
+    The basic XML looks like this::
+
+        <?xml version="1.0" encoding="UTF-8"?>
+        <song version="1.0">
+          <lyrics language="en">
+            <verse type="chorus" label="1">
+              <![CDATA[ ... ]]>
+            </verse>
+          </lyrics>
+        </song>
     """
     global log
     log = logging.getLogger(u'SongXMLParser')

=== modified file 'openlp/core/lib/themexmlhandler.py'
--- openlp/core/lib/themexmlhandler.py	2009-09-05 01:27:38 +0000
+++ openlp/core/lib/themexmlhandler.py	2009-09-06 18:59:21 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley, Carsten Tinggaard
 
 This program is free software; you can redistribute it and/or modify it under

=== modified file 'openlp/core/lib/toolbar.py'
--- openlp/core/lib/toolbar.py	2009-08-28 17:40:07 +0000
+++ openlp/core/lib/toolbar.py	2009-09-06 18:59:21 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2009 Raoul Snyman
+
 Portions copyright (c) 2009 Martin Thompson, Tim Bentley
 
 This program is free software; you can redistribute it and/or modify it under
@@ -109,9 +111,21 @@
             return QtGui.QIcon()
 
     def makeWidgetsInvisible(self, widgets):
+        """
+        Hide a set of widgets.
+
+        ``widgets``
+            The list of names of widgets to be hidden.
+        """
         for widget in widgets:
             self.actions[widget].setVisible(False)
 
     def makeWidgetsVisible(self, widgets):
+        """
+        Show a set of widgets.
+
+        ``widgets``
+            The list of names of widgets to be shown.
+        """
         for widget in widgets:
             self.actions[widget].setVisible(True)

=== modified file 'openlp/core/lib/xmlrootclass.py'
--- openlp/core/lib/xmlrootclass.py	2009-07-08 06:55:08 +0000
+++ openlp/core/lib/xmlrootclass.py	2009-07-14 13:51:27 +0000
@@ -2,7 +2,9 @@
 # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4
 """
 OpenLP - Open Source Lyrics Projection
+
 Copyright (c) 2008 Raoul Snyman
+
 Portions copyright (c) 2008 Martin Thompson, Tim Bentley, Carsten Tinggaard
 
 This program is free software; you can redistribute it and/or modify it under

=== modified file 'openlp/plugins/songs/songsplugin.py'
--- openlp/plugins/songs/songsplugin.py	2009-08-26 05:00:19 +0000
+++ openlp/plugins/songs/songsplugin.py	2009-09-02 20:42:57 +0000
@@ -28,12 +28,22 @@
     OpenSongImportForm, OpenLPExportForm
 
 class SongsPlugin(Plugin):
+    """
+    This is the number 1 plugin, if importance were placed on any
+    plugins. This plugin enables the user to create, edit and display
+    songs. Songs are divided into verses, and the verse order can be
+    specified. Authors, topics and song books can be assigned to songs
+    as well.
+    """
 
     global log
     log = logging.getLogger(u'SongsPlugin')
     log.info(u'Song Plugin loaded')
 
     def __init__(self, plugin_helpers):
+        """
+        Create and set up the Songs plugin.
+        """
         # Call the parent constructor
         Plugin.__init__(self, u'Songs', u'1.9.0', plugin_helpers)
         self.weight = -10
@@ -48,11 +58,22 @@
             QtGui.QIcon.Normal, QtGui.QIcon.Off)
 
     def get_media_manager_item(self):
-        # Create the MediaManagerItem object
+        """
+        Create the MediaManagerItem object, which is displaed in the
+        Media Manager.
+        """
         self.media_item = SongMediaItem(self, self.icon, 'Songs')
         return self.media_item
 
     def add_import_menu_item(self, import_menu):
+        """
+        Give the Songs plugin the opportunity to add items to the
+        **Import** menu.
+
+        ``import_menu``
+            The actual **Import** menu item, so that your actions can
+            use it as their parent.
+        """
         self.ImportSongMenu = QtGui.QMenu(import_menu)
         self.ImportSongMenu.setObjectName(u'ImportSongMenu')
         self.ImportOpenSongItem = QtGui.QAction(import_menu)
@@ -88,6 +109,14 @@
             QtCore.SIGNAL(u'triggered()'), self.onImportOpenSongItemClick)
 
     def add_export_menu_item(self, export_menu):
+        """
+        Give the Songs plugin the opportunity to add items to the
+        **Export** menu.
+
+        ``export_menu``
+            The actual **Export** menu item, so that your actions can
+            use it as their parent.
+        """
         self.ExportSongMenu = QtGui.QMenu(export_menu)
         self.ExportSongMenu.setObjectName(u'ExportSongMenu')
         self.ExportOpenSongItem = QtGui.QAction(export_menu)