Add DocStrings

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:`lib` 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:`lib` 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

@@ -310,8 +310,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
 
@@ -352,8 +351,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/theme/theme.py

@@ -22,7 +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.
+"""
 import types
 
 from xml.etree.ElementTree import ElementTree, XML
@@ -56,51 +61,59 @@ BLANK_STYLE_XML = \
 '''
 
 class Theme(object):
+    """
+    Provide a class wrapper storing data from an XML theme
+
+    Attributes:
+        name : theme name
+
+        BackgroundMode   : 1 - Transparent
+                           1 - Opaque
+
+        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
+    """
     def __init__(self, xml):
-        """ stores the info about a theme
+        """
-        attributes:
+        Initialise a theme with data from xml
-          name : theme name
-
-           BackgroundMode   : 1 - Transparent
-                             1 - Opaque
-
-          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()
@@ -110,6 +123,9 @@ class Theme(object):
         return u''.join(theme_strings)
 
     def _set_from_XML(self, xml):
+        """
+        Set theme class attributes with data from XML
+        """
         root = ElementTree(element=XML(xml))
         iter = root.getiterator()
         for element in iter:
@@ -149,8 +165,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/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/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/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,24 @@ class ThemeManager(QtGui.QWidget):
                 self.pushThemes()
 
     def onAddTheme(self):
+        """
+        Add a new theme
+
+        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):
+        """
+        Edit a theme
+
+        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 +195,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())
@@ -255,6 +278,13 @@ class ThemeManager(QtGui.QWidget):
                     zip.close()
 
     def onImportTheme(self):
+        """
+        Import a theme
+
+        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 (*.*)')
@@ -304,12 +334,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')
@@ -319,6 +361,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)
@@ -382,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
@@ -394,9 +445,13 @@ class ThemeManager(QtGui.QWidget):
 
     def migrateVersion122(self, filename, fullpath, 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
         """
         log.debug(u'migrateVersion122 %s %s', filename, fullpath)
         theme = Theme(xml_data)

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:`lib` module provides all the project produced plugins
+"""

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/presentations/lib/impresscontroller.py

@@ -372,11 +372,10 @@ class ImpressDocument(PresentationDocument):
 
     def get_slide_preview_file(self, slide_no):
         """
-        Returns an image path containing a preview for the
+        Returns an image path containing a preview for the requested slide
-        requested slide
 
         ``slide_no``
-        The slide an image is required for, starting at 1
+            The slide an image is required for, starting at 1
         """
         path = os.path.join(self.thumbnailpath,
             self.controller.thumbnailprefix + unicode(slide_no) + u'.png')

openlp/plugins/presentations/lib/powerpointcontroller.py

@@ -274,7 +274,7 @@ class PowerpointDocument(PresentationDocument):
         Returns an image path containing a preview for the requested slide
 
         ``slide_no``
-        The slide an image is required for, starting at 1
+            The slide an image is required for, starting at 1
         """
         path = os.path.join(self.thumbnailpath,
             self.controller.thumbnailprefix + unicode(slide_no) + u'.png')

openlp/plugins/songs/forms/__init__.py

@@ -26,6 +26,12 @@
 from openlp.core.lib import translate
 
 class VerseType(object):
+    """
+    Provide a type definition for verses
+
+    VerseType provides the type definition for the tags that may be associated
+    with verses in songs.
+    """
     Verse = 0
     Chorus = 1
     Bridge = 2
@@ -36,6 +42,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 +65,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