From 8d059fb84e8c4a845603bbbaee1ceaa54215586c Mon Sep 17 00:00:00 2001 From: Jon Tibble Date: Thu, 10 Jun 2010 02:57:59 +0100 Subject: [PATCH 1/5] Add DocStrings --- openlp/__init__.py | 3 + openlp/core/__init__.py | 6 ++ openlp/core/lib/mediamanageritem.py | 6 +- openlp/core/lib/pluginmanager.py | 4 +- openlp/core/theme/theme.py | 96 +++++++++++-------- openlp/core/ui/displaytab.py | 16 +++- openlp/core/ui/servicemanager.py | 4 +- openlp/core/ui/thememanager.py | 63 +++++++++++- openlp/plugins/__init__.py | 3 + openlp/plugins/alerts/forms/alertform.py | 11 ++- .../presentations/lib/impresscontroller.py | 5 +- .../presentations/lib/powerpointcontroller.py | 2 +- openlp/plugins/songs/forms/__init__.py | 18 ++++ 13 files changed, 180 insertions(+), 57 deletions(-) diff --git a/openlp/__init__.py b/openlp/__init__.py index 1a348a0df..516959992 100644 --- a/openlp/__init__.py +++ b/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 +""" diff --git a/openlp/core/__init__.py b/openlp/core/__init__.py index 1a348a0df..2fed22837 100644 --- a/openlp/core/__init__.py +++ b/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. +""" diff --git a/openlp/core/lib/mediamanageritem.py b/openlp/core/lib/mediamanageritem.py index 8bfefceb0..c4d439324 100644 --- a/openlp/core/lib/mediamanageritem.py +++ b/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 - automatically. + do any UI or other initialisation. This method is called automatically. """ pass @@ -352,8 +351,7 @@ class MediaManagerItem(QtGui.QWidget): def validate(self, file, thumb): """ - Validates to see if the file still exists or - thumbnail is up to date + Validates to see if the file still exists or thumbnail is up to date """ if os.path.exists(file): filedate = os.stat(file).st_mtime diff --git a/openlp/core/lib/pluginmanager.py b/openlp/core/lib/pluginmanager.py index 95bf3971c..d9ae40845 100644 --- a/openlp/core/lib/pluginmanager.py +++ b/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 diff --git a/openlp/core/theme/theme.py b/openlp/core/theme/theme.py index f63ee4c26..9c3c3ad6a 100644 --- a/openlp/core/theme/theme.py +++ b/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 or + + 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: - 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 or - - 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 + """ + Initialise a theme with data from xml """ # 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) + diff --git a/openlp/core/ui/displaytab.py b/openlp/core/ui/displaytab.py index 6fe9f16e2..3ddbb8b08 100644 --- a/openlp/core/ui/displaytab.py +++ b/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())) diff --git a/openlp/core/ui/servicemanager.py b/openlp/core/ui/servicemanager.py index a794a1c21..9664f8354 100644 --- a/openlp/core/ui/servicemanager.py +++ b/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 diff --git a/openlp/core/ui/thememanager.py b/openlp/core/ui/thememanager.py index f1d5ece34..2d526cac2 100644 --- a/openlp/core/ui/thememanager.py +++ b/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 - to the current format. - New fields are defaulted but the new theme is useable + Convert the xml data from version 1 format to the current format. + + 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) diff --git a/openlp/plugins/__init__.py b/openlp/plugins/__init__.py index 1a348a0df..8107bf60b 100644 --- a/openlp/plugins/__init__.py +++ b/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 +""" diff --git a/openlp/plugins/alerts/forms/alertform.py b/openlp/plugins/alerts/forms/alertform.py index 04028fc1b..012f195d1 100644 --- a/openlp/plugins/alerts/forms/alertform.py +++ b/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): diff --git a/openlp/plugins/presentations/lib/impresscontroller.py b/openlp/plugins/presentations/lib/impresscontroller.py index c1de03b2b..62f7da141 100644 --- a/openlp/plugins/presentations/lib/impresscontroller.py +++ b/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 - requested slide + 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') diff --git a/openlp/plugins/presentations/lib/powerpointcontroller.py b/openlp/plugins/presentations/lib/powerpointcontroller.py index 34cc6376e..532eacc1b 100644 --- a/openlp/plugins/presentations/lib/powerpointcontroller.py +++ b/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') diff --git a/openlp/plugins/songs/forms/__init__.py b/openlp/plugins/songs/forms/__init__.py index a336db465..79384637c 100644 --- a/openlp/plugins/songs/forms/__init__.py +++ b/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 From 3a7ca9a185ccea0f10b17458c315b72135e361e4 Mon Sep 17 00:00:00 2001 From: Jon Tibble Date: Thu, 10 Jun 2010 14:12:19 +0100 Subject: [PATCH 2/5] Fix module name thinkos --- openlp/__init__.py | 2 +- openlp/core/__init__.py | 2 +- openlp/plugins/__init__.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/openlp/__init__.py b/openlp/__init__.py index 516959992..98d19aecc 100644 --- a/openlp/__init__.py +++ b/openlp/__init__.py @@ -23,5 +23,5 @@ # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### """ -The :mod:`lib` module contains all the project produced OpenLP functionality +The :mod:`openlp` module contains all the project produced OpenLP functionality """ diff --git a/openlp/core/__init__.py b/openlp/core/__init__.py index 2fed22837..5b2bbe056 100644 --- a/openlp/core/__init__.py +++ b/openlp/core/__init__.py @@ -23,7 +23,7 @@ # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### """ -The :mod:`lib` module provides all core application functions +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. diff --git a/openlp/plugins/__init__.py b/openlp/plugins/__init__.py index 8107bf60b..213c15d47 100644 --- a/openlp/plugins/__init__.py +++ b/openlp/plugins/__init__.py @@ -23,5 +23,5 @@ # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### """ -The :mod:`lib` module provides all the project produced plugins +The :mod:`plugins` module provides all the project produced plugins """ From 0e07c0f6648438cb3671b79d577444d0a72346d3 Mon Sep 17 00:00:00 2001 From: Jon Tibble Date: Thu, 10 Jun 2010 15:09:32 +0100 Subject: [PATCH 3/5] Use reStructuredText in Theme --- openlp/core/theme/theme.py | 112 +++++++++++++++++++++++++++---------- 1 file changed, 81 insertions(+), 31 deletions(-) diff --git a/openlp/core/theme/theme.py b/openlp/core/theme/theme.py index 9c3c3ad6a..9b0c2f54c 100644 --- a/openlp/core/theme/theme.py +++ b/openlp/core/theme/theme.py @@ -64,47 +64,94 @@ class Theme(object): """ Provide a class wrapper storing data from an XML theme - Attributes: - name : theme name + ``name`` + Theme name - BackgroundMode : 1 - Transparent - 1 - Opaque + ``BackgroundMode`` + The behaviour of the background. Valid modes are: + - 0 - Transparent + - 1 - Opaque - BackgroundType : 0 - solid color - 1 - gradient color - 2 - image + ``BackgroundType`` + The content of the background. Valid types are: + - 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 + ``BackgroundParameter1`` + Extra information about the background. The contents of this attribute + depend on the BackgroundType: + - image: image filename + - gradient: start color + - solid: color - FontName : name of font to use - FontColor : color for main font - FontProportion : size of font - FontUnits : whether size of font is in or + ``BackgroundParameter2`` + Extra information about the background. The contents of this attribute + depend on the BackgroundType: + - image: border color + - gradient: end color + - solid: N/A - 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) + ``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 - 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 + ``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 or + + ``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): """ Initialise a theme with data from xml + + ``xml`` + The data to initialise the theme with """ # init to defaults self._set_from_XML(BLANK_STYLE_XML) @@ -125,6 +172,9 @@ class Theme(object): 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() From 78114b80630f3dc701bc5b40e22862535ebc9cce Mon Sep 17 00:00:00 2001 From: Jon Tibble Date: Thu, 10 Jun 2010 20:45:02 +0100 Subject: [PATCH 4/5] Apply docstrings feedback --- openlp/core/ui/__init__.py | 3 +++ openlp/core/ui/thememanager.py | 26 ++++++++++++++++++++------ openlp/core/utils/__init__.py | 5 ++++- openlp/plugins/songs/forms/__init__.py | 4 +--- 4 files changed, 28 insertions(+), 10 deletions(-) diff --git a/openlp/core/ui/__init__.py b/openlp/core/ui/__init__.py index 76b84503e..e104a2ec6 100644 --- a/openlp/core/ui/__init__.py +++ b/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): """ diff --git a/openlp/core/ui/thememanager.py b/openlp/core/ui/thememanager.py index b5322d0ec..1d60d264f 100644 --- a/openlp/core/ui/thememanager.py +++ b/openlp/core/ui/thememanager.py @@ -168,8 +168,6 @@ class ThemeManager(QtGui.QWidget): 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. """ @@ -180,8 +178,6 @@ class ThemeManager(QtGui.QWidget): 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. """ @@ -286,8 +282,6 @@ class ThemeManager(QtGui.QWidget): 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. @@ -565,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'))) @@ -583,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) @@ -590,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() diff --git a/openlp/core/utils/__init__.py b/openlp/core/utils/__init__.py index 8cbf7657a..512e15f06 100644 --- a/openlp/core/utils/__init__.py +++ b/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 diff --git a/openlp/plugins/songs/forms/__init__.py b/openlp/plugins/songs/forms/__init__.py index 84e75c202..a96e092c4 100644 --- a/openlp/plugins/songs/forms/__init__.py +++ b/openlp/plugins/songs/forms/__init__.py @@ -27,9 +27,7 @@ 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 + VerseType provides an enumeration for the tags that may be associated with verses in songs. """ Verse = 0 From 914a710f955768050b413ba194781896ba35bf1d Mon Sep 17 00:00:00 2001 From: Jon Tibble Date: Thu, 10 Jun 2010 22:30:50 +0100 Subject: [PATCH 5/5] More docstrings --- openlp/core/lib/serviceitem.py | 37 ++++++++++++++++++++++++++++++ openlp/core/lib/songxmlhandler.py | 36 +++++++++++------------------ openlp/core/ui/mediadockmanager.py | 22 +++++++++++++++++- openlp/core/ui/screen.py | 11 ++++++++- openlp/core/ui/settingsform.py | 26 +++++++++++++++++++-- openlp/plugins/alerts/__init__.py | 4 ++++ openlp/plugins/bibles/__init__.py | 4 ++++ 7 files changed, 114 insertions(+), 26 deletions(-) diff --git a/openlp/core/lib/serviceitem.py b/openlp/core/lib/serviceitem.py index 9fe7ac060..6f27ddf34 100644 --- a/openlp/core/lib/serviceitem.py +++ b/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: diff --git a/openlp/core/lib/songxmlhandler.py b/openlp/core/lib/songxmlhandler.py index acb75609b..76b01e376 100644 --- a/openlp/core/lib/songxmlhandler.py +++ b/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:: + + + + + + + + + +""" 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:: - - - - - - - - - """ 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:: - - - - - - - - - """ log.info(u'SongXMLParser Loaded') diff --git a/openlp/core/ui/mediadockmanager.py b/openlp/core/ui/mediadockmanager.py index 782383cd4..7d81b5f23 100644 --- a/openlp/core/ui/mediadockmanager.py +++ b/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): diff --git a/openlp/core/ui/screen.py b/openlp/core/ui/screen.py index 69dd915d2..f620e7d00 100644 --- a/openlp/core/ui/screen.py +++ b/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 diff --git a/openlp/core/ui/settingsform.py b/openlp/core/ui/settingsform.py index f923c9d7d..dfd1d5a7d 100644 --- a/openlp/core/ui/settingsform.py +++ b/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() diff --git a/openlp/plugins/alerts/__init__.py b/openlp/plugins/alerts/__init__.py index 1a348a0df..cb376ec38 100644 --- a/openlp/plugins/alerts/__init__.py +++ b/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 +""" diff --git a/openlp/plugins/bibles/__init__.py b/openlp/plugins/bibles/__init__.py index 1a348a0df..ca5ff7508 100644 --- a/openlp/plugins/bibles/__init__.py +++ b/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 +"""