From 8d059fb84e8c4a845603bbbaee1ceaa54215586c Mon Sep 17 00:00:00 2001 From: Jon Tibble Date: Thu, 10 Jun 2010 02:57:59 +0100 Subject: [PATCH] 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