DocStrings

bzr-revno: 840

openlp/__init__.py

@@ -22,3 +22,6 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`openlp` module contains all the project produced OpenLP functionality
+"""

openlp/core/__init__.py

@@ -22,3 +22,9 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`core` module provides all core application functions
+
+All the core functions of the OpenLP application including the GUI, settings,
+logging and a plugin framework are contained within the openlp.core module.
+"""

openlp/core/lib/mediamanageritem.py

@@ -309,8 +309,7 @@ class MediaManagerItem(QtGui.QWidget):
     def initialise(self):
         """
         Implement this method in your descendent media manager item to
-        do any UI or other initialisation. This method is called
+        do any UI or other initialisation. This method is called automatically.
-        automatically.
         """
         pass
 
@@ -351,8 +350,7 @@ class MediaManagerItem(QtGui.QWidget):
 
     def validate(self, file, thumb):
         """
-        Validates to see if the file still exists or
+        Validates to see if the file still exists or thumbnail is up to date
-        thumbnail is up to date
         """
         if os.path.exists(file):
             filedate = os.stat(file).st_mtime

openlp/core/lib/pluginmanager.py

@@ -22,7 +22,9 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
-
+"""
+Provide plugin management
+"""
 import os
 import sys
 import logging

openlp/core/lib/serviceitem.py

@@ -22,6 +22,10 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`serviceitem` provides the service item functionality including the
+type and capability of an item.
+"""
 
 import logging
 import os
@@ -43,6 +47,9 @@ class ServiceItemType(object):
     Command = 3
 
 class ItemCapabilities(object):
+    """
+    Provides an enumeration of a serviceitem's capabilities
+    """
     AllowsPreview = 1
     AllowsEdit = 2
     AllowsMaintain = 3
@@ -85,9 +92,21 @@ class ServiceItem(object):
         self.cache = []
 
     def add_capability(self, capability):
+        """
+        Add an ItemCapability to a ServiceItem
+
+        ``capability``
+            The capability to add
+        """
         self.capabilities.append(capability)
 
     def is_capable(self, capability):
+        """
+        Tell the caller if a ServiceItem has a capability
+
+        ``capability``
+            The capability to test for
+        """
         return capability in self.capabilities
 
     def addIcon(self, icon):
@@ -304,22 +323,40 @@ class ServiceItem(object):
         return self._uuid != other._uuid
 
     def is_media(self):
+        """
+        Confirms if the ServiceItem is media
+        """
         return ItemCapabilities.RequiresMedia in self.capabilities
 
     def is_command(self):
+        """
+        Confirms if the ServiceItem is a command
+        """
         return self.service_item_type == ServiceItemType.Command
 
     def is_image(self):
+        """
+        Confirms if the ServiceItem is an image
+        """
         return self.service_item_type == ServiceItemType.Image
 
     def uses_file(self):
+        """
+        Confirms if the ServiceItem uses a file
+        """
         return self.service_item_type == ServiceItemType.Image or \
             self.service_item_type == ServiceItemType.Command
 
     def is_text(self):
+        """
+        Confirms if the ServiceItem is text
+        """
         return self.service_item_type == ServiceItemType.Text
 
     def get_frames(self):
+        """
+        Returns the frames for the ServiceItem
+        """
         if self.service_item_type == ServiceItemType.Text:
             return self._display_frames
         else:

openlp/core/lib/songxmlhandler.py

@@ -22,6 +22,20 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`songxmlhandler` module provides the XML functionality for songs
+
+The basic XML is of the format::
+
+    <?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
 
@@ -34,17 +48,6 @@ log = logging.getLogger(__name__)
 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>
     """
     log.info(u'SongXMLBuilder Loaded')
 
@@ -113,17 +116,6 @@ class SongXMLBuilder(object):
 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>
     """
     log.info(u'SongXMLParser Loaded')
 

openlp/core/theme/theme.py

@@ -22,6 +22,12 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+OpenLP version 1 theme handling
+
+Provides reference data, a default v1 XML theme and class wrapper for
+processing version 1 themes in OpenLP version 2.
+"""
 
 from xml.etree.ElementTree import ElementTree, XML
 from PyQt4 import QtGui
@@ -54,51 +60,106 @@ BLANK_STYLE_XML = \
 '''
 
 class Theme(object):
+    """
+    Provide a class wrapper storing data from an XML theme
+
+    ``name``
+        Theme name
+
+    ``BackgroundMode``
+        The behaviour of the background.  Valid modes are:
+            - 0 - Transparent
+            - 1 - Opaque
+
+    ``BackgroundType``
+        The content of the background.  Valid types are:
+            - 0 - solid color
+            - 1 - gradient color
+            - 2 - image
+
+    ``BackgroundParameter1``
+        Extra information about the background.  The contents of this attribute
+        depend on the BackgroundType:
+            - image: image filename
+            - gradient: start color
+            - solid: color
+
+    ``BackgroundParameter2``
+        Extra information about the background.  The contents of this attribute
+        depend on the BackgroundType:
+            - image: border color
+            - gradient: end color
+            - solid: N/A
+
+    ``BackgroundParameter3``
+        Extra information about the background.  The contents of this attribute
+        depend on the BackgroundType:
+            - image: N/A
+            - gradient: The direction of the gradient. Valid entries are:
+                - 0 -> vertical
+                - 1 -> horizontal
+            - solid: N/A
+
+    ``FontName``
+        Name of the font to use for the main font.
+
+    ``FontColor``
+        The color for the main font
+
+    ``FontProportion``
+        The size of the main font
+
+    ``FontUnits``
+        The units for FontProportion, either <pixels> or <points>
+
+    ``Shadow``
+        The shadow type to apply to the main font.
+            - 0 - no shadow
+            - non-zero - use shadow
+
+    ``ShadowColor``
+        Color for the shadow
+
+    ``Outline``
+        The outline to apply to the main font
+            - 0 - no outline
+            - non-zero - use outline
+
+    ``OutlineColor``
+        Color for the outline (or None if Outline is 0)
+
+    ``HorizontalAlign``
+        The horizontal alignment to apply to text.  Valid alignments are:
+            - 0 - left align
+            - 1 - right align
+            - 2 - centre align
+
+    ``VerticalAlign``
+        The vertical alignment to apply to the text. Valid alignments are:
+            - 0 - top align
+            - 1 - bottom align
+            - 2 - centre align
+
+    ``WrapStyle``
+        The wrap style to apply to the text.  Valid styles are:
+            - 0 - normal
+            - 1 - lyrics
+    """
     def __init__(self, xml):
-        """ stores the info about a theme
+        """
-        attributes:
+        Initialise a theme with data from xml
-          name : theme name
 
-           BackgroundMode   : 1 - Transparent
+        ``xml``
-                             1 - Opaque
+            The data to initialise the theme with
-
-          BackgroundType   : 0 - solid color
-                             1 - gradient color
-                             2 - image
-
-          BackgroundParameter1 : for image - filename
-                                 for gradient - start color
-                                 for solid - color
-          BackgroundParameter2 : for image - border colour
-                                 for gradient - end color
-                                 for solid - N/A
-          BackgroundParameter3 : for image - N/A
-                                 for gradient - 0 -> vertical, 1 -> horizontal
-
-          FontName       : name of font to use
-          FontColor      : color for main font
-          FontProportion : size of font
-          FontUnits      : whether size of font is in <pixels> or <points>
-
-          Shadow       : 0 - no shadow, non-zero use shadow
-          ShadowColor  : color for drop shadow
-          Outline      : 0 - no outline, non-zero use outline
-          OutlineColor : color for outline (or None for no outline)
-
-          HorizontalAlign : 0 - left align
-                            1 - right align
-                            2 - centre align
-          VerticalAlign   : 0 - top align
-                            1 - bottom align
-                            2 - centre align
-          WrapStyle       : 0 - normal
-                            1 - lyrics
         """
         # init to defaults
         self._set_from_XML(BLANK_STYLE_XML)
         self._set_from_XML(xml)
 
     def _get_as_string(self):
+        """
+        Return single line string representation of a theme
+        """
         theme_strings = []
         keys = dir(self)
         keys.sort()
@@ -108,6 +169,12 @@ class Theme(object):
         return u''.join(theme_strings)
 
     def _set_from_XML(self, xml):
+        """
+        Set theme class attributes with data from XML
+
+        ``xml``
+            The data to apply to the theme
+        """
         root = ElementTree(element=XML(xml))
         iter = root.getiterator()
         for element in iter:
@@ -146,8 +213,12 @@ class Theme(object):
                 setattr(self, element.tag, val)
 
     def __str__(self):
+        """
+        Provide Python string representation for the class (multiline output)
+        """
         theme_strings = []
         for key in dir(self):
             if key[0:1] != u'_':
                 theme_strings.append(u'%30s : %s' % (key, getattr(self, key)))
         return u'\n'.join(theme_strings)
+

openlp/core/ui/__init__.py

@@ -22,6 +22,9 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`ui` module provides the core user interface for OpenLP
+"""
 
 class HideMode(object):
     """

openlp/core/ui/displaytab.py

@@ -29,16 +29,19 @@ from openlp.core.lib import SettingsTab, Receiver, translate
 
 class DisplayTab(SettingsTab):
     """
-    Class documentation goes here.
+    Provide the UI for managing display related settings
     """
     def __init__(self, screens):
         """
-        Constructor
+        Initialise the display tab from a SettingsTab
         """
         self.screens = screens
         SettingsTab.__init__(self, u'Display')
 
     def setupUi(self):
+        """
+        Set up the UI widgets to show the settings
+        """
         self.tabTitleVisible = translate(u'DisplayTab', u'Displays')
         self.layoutWidget = QtGui.QWidget(self)
         self.layoutWidget.setGeometry(QtCore.QRect(0, 40, 241, 79))
@@ -158,6 +161,9 @@ class DisplayTab(SettingsTab):
             QtCore.SIGNAL(u'stateChanged(int)'), self.onOverrideCheckBoxChanged)
 
     def retranslateUi(self):
+        """
+        Provide i18n support for this UI
+        """
         self.setWindowTitle(translate(u'DisplayTab', u'Amend Display Settings'))
         self.CurrentGroupBox.setTitle(
             translate(u'DisplayTab', u'Default Settings'))
@@ -179,6 +185,9 @@ class DisplayTab(SettingsTab):
             translate(u'DisplayTab', u'Override Output Display'))
 
     def load(self):
+        """
+        Load current display settings
+        """
         settings = QtCore.QSettings()
         settings.beginGroup(self.settingsSection)
         self.Xpos.setText(unicode(self.screens.current[u'size'].x()))
@@ -209,6 +218,9 @@ class DisplayTab(SettingsTab):
             self.amend_display = True
 
     def save(self):
+        """
+        Save chosen settings
+        """
         settings = QtCore.QSettings()
         settings.beginGroup(self.settingsSection)
         settings.setValue('x position', QtCore.QVariant(self.XposEdit.text()))

openlp/core/ui/mediadockmanager.py

@@ -28,11 +28,25 @@ import logging
 log = logging.getLogger(__name__)
 
 class MediaDockManager(object):
-
+    """
+    Provide a repository for MediaManagerItems
+    """
     def __init__(self, media_dock):
+        """
+        Initialise the media dock
+        """
         self.media_dock = media_dock
 
     def add_dock(self, media_item, icon, weight):
+        """
+        Add a MediaManagerItem to the dock
+
+        ``media_item``
+            The item to add to the dock
+
+        ``icon``
+            An icon for this dock item
+        """
         log.info(u'Adding %s dock' % media_item.title)
         self.media_dock.addItem(media_item, icon, media_item.title)
 
@@ -53,6 +67,12 @@ class MediaDockManager(object):
             self.media_dock.addItem(media_item, icon, media_item.title)
 
     def remove_dock(self, name):
+        """
+        Removes a MediaManagerItem from the dock
+
+        ``name``
+            The item to remove
+        """
         log.debug(u'remove %s dock' % name)
         for dock_index in range(0, self.media_dock.count()):
             if self.media_dock.widget(dock_index):

openlp/core/ui/screen.py

@@ -22,7 +22,10 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
-
+"""
+The :mod:`screen` module provides management functionality for a machines'
+displays
+"""
 import logging
 import copy
 
@@ -46,12 +49,18 @@ class ScreenList(object):
         self.monitor_number = 0
 
     def add_screen(self, screen):
+        """
+        Add a screen to the list of known screens
+        """
         if screen[u'primary']:
             self.current = screen
         self.screen_list.append(screen)
         self.display_count += 1
 
     def screen_exists(self, number):
+        """
+        Confirms a screen is known
+        """
         for screen in self.screen_list:
             if screen[u'number'] == number:
                 return True

openlp/core/ui/servicemanager.py

@@ -38,7 +38,9 @@ from openlp.core.ui import ServiceNoteForm, ServiceItemEditForm
 from openlp.core.utils import AppLocation
 
 class ServiceManagerList(QtGui.QTreeWidget):
-
+    """
+    Set up key bindings and mouse behaviour for the service list
+    """
     def __init__(self, parent=None, name=None):
         QtGui.QTreeWidget.__init__(self, parent)
         self.parent = parent

openlp/core/ui/settingsform.py

@@ -22,7 +22,9 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
-
+"""
+The :mod:`settingsform` provides a user interface for the OpenLP settings
+"""
 import logging
 
 from PyQt4 import QtGui
@@ -33,8 +35,13 @@ from settingsdialog import Ui_SettingsDialog
 log = logging.getLogger(__name__)
 
 class SettingsForm(QtGui.QDialog, Ui_SettingsDialog):
-
+    """
+    Provide the form to manipulate the settings for OpenLP
+    """
     def __init__(self, screens, mainWindow, parent=None):
+        """
+        Initialise the settings form
+        """
         QtGui.QDialog.__init__(self, parent)
         self.setupUi(self)
         # General tab
@@ -48,16 +55,25 @@ class SettingsForm(QtGui.QDialog, Ui_SettingsDialog):
         self.addTab(u'Display', self.DisplayTab)
 
     def addTab(self, name, tab):
+        """
+        Add a tab to the form
+        """
         log.info(u'Adding %s tab' % tab.tabTitle)
         self.SettingsTabWidget.addTab(tab, tab.tabTitleVisible)
 
     def insertTab(self, tab, location):
+        """
+        Add a tab to the form at a specific location
+        """
         log.debug(u'Inserting %s tab' % tab.tabTitle)
         #13 : There are 3 tables currently and locations starts at -10
         self.SettingsTabWidget.insertTab(
             location + 13, tab, tab.tabTitleVisible)
 
     def removeTab(self, name):
+        """
+        Remove a tab from the form
+        """
         log.debug(u'remove %s tab' % name)
         for tab_index in range(0, self.SettingsTabWidget.count()):
             if self.SettingsTabWidget.widget(tab_index):
@@ -65,10 +81,16 @@ class SettingsForm(QtGui.QDialog, Ui_SettingsDialog):
                     self.SettingsTabWidget.removeTab(tab_index)
 
     def accept(self):
+        """
+        Process the form saving the settings
+        """
         for tab_index in range(0, self.SettingsTabWidget.count()):
             self.SettingsTabWidget.widget(tab_index).save()
         return QtGui.QDialog.accept(self)
 
     def postSetUp(self):
+        """
+        Run any post-setup code for the tabs on the form
+        """
         for tab_index in range(0, self.SettingsTabWidget.count()):
             self.SettingsTabWidget.widget(tab_index).postSetUp()

openlp/core/ui/thememanager.py

@@ -121,6 +121,10 @@ class ThemeManager(QtGui.QWidget):
             QtCore.QVariant(u'')).toString())
 
     def changeGlobalFromTab(self, themeName):
+        """
+        Change the global theme when it is changed through the Themes settings
+        tab
+        """
         log.debug(u'changeGlobalFromTab %s', themeName)
         for count in range (0, self.ThemeListWidget.count()):
             #reset the old name
@@ -136,6 +140,10 @@ class ThemeManager(QtGui.QWidget):
                 self.ThemeListWidget.item(count).setText(name)
 
     def changeGlobalFromScreen(self, index = -1):
+        """
+        Change the global theme when a theme is double clicked upon in the
+        Theme Manager list
+        """
         log.debug(u'changeGlobalFromScreen %s', index)
         selected_row = self.ThemeListWidget.currentRow()
         for count in range (0, self.ThemeListWidget.count()):
@@ -159,12 +167,20 @@ class ThemeManager(QtGui.QWidget):
                 self.pushThemes()
 
     def onAddTheme(self):
+        """
+        Loads a new theme with the default settings and then launches the theme
+        editing form for the user to make their customisations.
+        """
         theme = self.createThemeFromXml(self.baseTheme(), self.path)
         self.amendThemeForm.loadTheme(theme)
         self.saveThemeName = u''
         self.amendThemeForm.exec_()
 
     def onEditTheme(self):
+        """
+        Loads the settings for the theme that is to be edited and launches the
+        theme editing form so the user can make their changes.
+        """
         item = self.ThemeListWidget.currentItem()
         if item:
             theme = self.getThemeData(
@@ -175,6 +191,9 @@ class ThemeManager(QtGui.QWidget):
             self.amendThemeForm.exec_()
 
     def onDeleteTheme(self):
+        """
+        Delete a theme
+        """
         self.global_theme = unicode(QtCore.QSettings().value(
             self.settingsSection + u'/global theme',
             QtCore.QVariant(u'')).toString())
@@ -262,6 +281,11 @@ class ThemeManager(QtGui.QWidget):
                     zip.close()
 
     def onImportTheme(self):
+        """
+        Opens a file dialog to select the theme file(s) to import before
+        attempting to extract OpenLP themes from those files.  This process
+        will load both OpenLP version 1 and version 2 themes.
+        """
         files = QtGui.QFileDialog.getOpenFileNames(
             self, translate(u'ThemeManager', u'Select Theme Import File'),
             SettingsManager.get_last_dir(self.settingsSection), u'Theme (*.*)')
@@ -311,12 +335,24 @@ class ThemeManager(QtGui.QWidget):
         self.pushThemes()
 
     def pushThemes(self):
+        """
+        Notify listeners that the theme list has been updated
+        """
         Receiver.send_message(u'theme_update_list', self.getThemes())
 
     def getThemes(self):
+        """
+        Return the list of loaded themes
+        """
         return self.themelist
 
     def getThemeData(self, themename):
+        """
+        Returns a theme object from an XML file
+
+        ``themename``
+            Name of the theme to load from file
+        """
         log.debug(u'getthemedata for theme %s', themename)
         xml_file = os.path.join(self.path, unicode(themename),
             unicode(themename) + u'.xml')
@@ -326,6 +362,12 @@ class ThemeManager(QtGui.QWidget):
         return self.createThemeFromXml(xml, self.path)
 
     def checkThemesExists(self, dir):
+        """
+        Check a theme directory exists and if not create it
+
+        ``dir``
+            Theme directory to make sure exists
+        """
         log.debug(u'check themes')
         if not os.path.exists(dir):
             os.mkdir(dir)
@@ -388,7 +430,10 @@ class ThemeManager(QtGui.QWidget):
 
     def checkVersion1(self, xmlfile):
         """
-        Am I a version 1 theme
+        Check if a theme is from OpenLP version 1
+
+        ``xmlfile``
+            Theme XML to check the version of
         """
         log.debug(u'checkVersion1 ')
         theme = xmlfile
@@ -400,9 +445,13 @@ class ThemeManager(QtGui.QWidget):
 
     def migrateVersion122(self, xml_data):
         """
-        Called by convert the xml data from version 1 format
+        Convert the xml data from version 1 format to the current format.
-        to the current format.
+
-        New fields are defaulted but the new theme is useable
+        New fields are loaded with defaults to provide a complete, working
+        theme containing all compatible customisations from the old theme.
+
+        ``xml_data``
+            Version 1 theme to convert
         """
         theme = Theme(xml_data)
         newtheme = ThemeXML()
@@ -510,11 +559,20 @@ class ThemeManager(QtGui.QWidget):
         return frame
 
     def getPreviewImage(self, theme):
+        """
+        Return an image representing the look of the theme
+
+        ``theme``
+            The theme to return the image for
+        """
         log.debug(u'getPreviewImage %s ', theme)
         image = os.path.join(self.path, theme + u'.png')
         return image
 
     def baseTheme(self):
+        """
+        Provide a base theme with sensible defaults
+        """
         log.debug(u'base theme created')
         newtheme = ThemeXML()
         newtheme.new_document(unicode(translate(u'ThemeManager', u'New Theme')))
@@ -528,6 +586,12 @@ class ThemeManager(QtGui.QWidget):
         return newtheme.extract_xml()
 
     def createThemeFromXml(self, theme_xml, path):
+        """
+        Return a theme object using information parsed from XML
+
+        ``theme_xml``
+            The XML data to load into the theme
+        """
         theme = ThemeXML()
         theme.parse(theme_xml)
         self.cleanTheme(theme)
@@ -535,6 +599,11 @@ class ThemeManager(QtGui.QWidget):
         return theme
 
     def cleanTheme(self, theme):
+        """
+        Clean a theme loaded from an XML file by removing stray whitespace and
+        making sure parameters are the correct type for the theme object
+        attributes
+        """
         theme.background_color = theme.background_color.strip()
         theme.background_direction = theme.background_direction.strip()
         theme.background_endColor = theme.background_endColor.strip()

openlp/core/utils/__init__.py

@@ -22,13 +22,16 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`utils` module provides the utility libraries for OpenLP
+"""
 
 import os
 import sys
 import logging
 import urllib2
-from datetime import datetime
 
+from datetime import datetime
 from PyQt4 import QtCore
 
 import openlp

openlp/plugins/__init__.py

@@ -22,3 +22,6 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`plugins` module provides all the project produced plugins
+"""

openlp/plugins/alerts/__init__.py

@@ -22,3 +22,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`alerts` module provides the Alerts plugin for producing impromptu
+on-screen announcements during a service
+"""

openlp/plugins/alerts/forms/alertform.py

@@ -32,11 +32,11 @@ from alertdialog import Ui_AlertDialog
 
 class AlertForm(QtGui.QDialog, Ui_AlertDialog):
     """
-    Class documentation goes here.
+    Provide UI for the alert system
     """
     def __init__(self, manager, parent):
         """
-        Constructor
+        Initialise the alert form
         """
         self.manager = manager
         self.parent = parent
@@ -103,6 +103,9 @@ class AlertForm(QtGui.QDialog, Ui_AlertDialog):
         self.loadList()
 
     def onSaveClick(self):
+        """
+        Save an alert
+        """
         if self.item_id:
             alert = self.manager.get_alert(self.item_id)
             alert.text = unicode(self.AlertTextEdit.text())
@@ -113,7 +116,9 @@ class AlertForm(QtGui.QDialog, Ui_AlertDialog):
             self.onNewClick()
 
     def onTextChanged(self):
-        #Data has changed by editing it so potential storage required
+        """
+        Enable save button when data has been changed by editing the form
+        """
         self.SaveButton.setEnabled(True)
 
     def onDoubleClick(self):

openlp/plugins/bibles/__init__.py

@@ -22,3 +22,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc., 59  #
 # Temple Place, Suite 330, Boston, MA 02111-1307 USA                          #
 ###############################################################################
+"""
+The :mod:`bibles' modules provides the Bible plugin to enable OpenLP to display
+scripture
+"""

openlp/plugins/songs/forms/__init__.py

@@ -26,6 +26,10 @@
 from openlp.core.lib import translate
 
 class VerseType(object):
+    """
+    VerseType provides an enumeration for the tags that may be associated
+    with verses in songs.
+    """
     Verse = 0
     Chorus = 1
     Bridge = 2
@@ -36,6 +40,12 @@ class VerseType(object):
 
     @staticmethod
     def to_string(verse_type):
+        """
+        Return a string for a given VerseType
+
+        ``verse_type``
+            The type to return a string for
+        """
         if verse_type == VerseType.Verse:
             return translate(u'VerseType', u'Verse')
         elif verse_type == VerseType.Chorus:
@@ -53,6 +63,12 @@ class VerseType(object):
 
     @staticmethod
     def from_string(verse_type):
+        """
+        Return the VerseType for a given string
+
+        ``verse_type``
+            The string to return a VerseType for
+        """
         verse_type = verse_type.lower()
         if verse_type == unicode(VerseType.to_string(VerseType.Verse)).lower():
             return VerseType.Verse