diff --git a/documentation/source/conf.py b/documentation/source/conf.py index 05a3045df..6f3aca825 100644 --- a/documentation/source/conf.py +++ b/documentation/source/conf.py @@ -47,7 +47,7 @@ copyright = u'2009, Raoul Snyman' # The short X.Y version. version = '2.0' # The full version, including alpha/beta/rc tags. -release = '1.9.0' +release = '2.0.pre' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -96,7 +96,14 @@ html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +html_theme_options = { + 'sidebarbgcolor': '#3a60a9', + 'relbarbgcolor': '#203b6f', + 'footerbgcolor': '#26437c', + 'headtextcolor': '#203b6f', + 'linkcolor': '#26437c', + 'sidebarlinkcolor': '#ceceff' +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] diff --git a/documentation/source/core/index.rst b/documentation/source/core/index.rst index 11597067c..38a98ab97 100644 --- a/documentation/source/core/index.rst +++ b/documentation/source/core/index.rst @@ -3,42 +3,9 @@ :mod:`core` Module ================== -.. automodule:: openlp.core - :members: +.. toctree:: + :maxdepth: 2 -:mod:`lib` Module ------------------ - -.. automodule:: openlp.core.lib - :members: - -:mod:`baselistwithdnd` Submodule -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: openlp.core.lib.baselistwithdnd - :members: - -:mod:`event` Submodule -^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: openlp.core.lib.event - :members: - -:mod:`eventmanager` Submodule -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: openlp.core.lib.eventmanager - :members: - -:mod:`eventreceiver` Submodule -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: openlp.core.lib.eventreceiver - :members: - -:mod:`theme` Submodule ----------------------- - -.. automodule:: openlp.core.theme - :members: + lib + theme diff --git a/documentation/source/core/lib.rst b/documentation/source/core/lib.rst new file mode 100644 index 000000000..c694cb91c --- /dev/null +++ b/documentation/source/core/lib.rst @@ -0,0 +1,110 @@ +.. _core-lib: + +:mod:`lib` Module +================= + +Module Members +-------------- + +.. automodule:: openlp.core.lib + :members: + +Module Classes +-------------- + +:mod:`BaseListWithDnD` +^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.baselistwithdnd.BaseListWithDnD + :members: + +:mod:`EventReceiver` +^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.eventreceiver.EventReceiver + :members: + +:mod:`ListWithPreviews` +^^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.listwithpreviews.ListWithPreviews + :members: + +:mod:`MediaManagerItem` +^^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.mediamanageritem.MediaManagerItem + :members: + +:mod:`Plugin` +^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.plugin.Plugin + :members: + +:mod:`PluginConfig` +^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.pluginconfig.PluginConfig + :members: + +:mod:`PluginManager` +^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.pluginmanager.PluginManager + :members: + +:mod:`Renderer` +^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.renderer.Renderer + :members: + +:mod:`RenderManager` +^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.rendermanager.RenderManager + :members: + +:mod:`ServiceItem` +^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.serviceitem.ServiceItem + :members: + +:mod:`SettingsTab` +^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.settingstab.SettingsTab + :members: + +:mod:`SongXMLBuilder` +^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.songxmlhandler.SongXMLBuilder + :members: + +:mod:`SongXMLParser` +^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.songxmlhandler.SongXMLParser + :members: + +:mod:`ThemeXML` +^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.themexmlhandler.ThemeXML + :members: + +:mod:`OpenLPToolbar` +^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.toolbar.OpenLPToolbar + :members: + +:mod:`XmlRootClass` +^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.core.lib.xmlrootclass.XmlRootClass + :members: + diff --git a/documentation/source/core/theme.rst b/documentation/source/core/theme.rst new file mode 100644 index 000000000..3dbc7a6ec --- /dev/null +++ b/documentation/source/core/theme.rst @@ -0,0 +1,8 @@ +.. _core-theme: + +:mod:`theme` Module +=================== + +.. automodule:: openlp.core.theme + :members: + diff --git a/documentation/source/index.rst b/documentation/source/index.rst index d57a43543..25fc13758 100644 --- a/documentation/source/index.rst +++ b/documentation/source/index.rst @@ -3,8 +3,12 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to OpenLP's documentation! -================================== +Welcome +======= + +Welcome to the OpenLP 2.0 API Documentation! In here you will find all +information relating to OpenLP's core classes, core plugins, and anything else +deemed necessary or interesting by the developers. Contents: diff --git a/documentation/source/plugins/index.rst b/documentation/source/plugins/index.rst index e618fa188..848f5a206 100644 --- a/documentation/source/plugins/index.rst +++ b/documentation/source/plugins/index.rst @@ -6,11 +6,10 @@ .. automodule:: openlp.plugins :members: -:mod:`songs` Plugin -------------------- +.. toctree:: + :maxdepth: 2 -.. automodule:: openlp.plugins.songs - :members: + songs :mod:`bibles` Plugin -------------------- diff --git a/documentation/source/plugins/songs.rst b/documentation/source/plugins/songs.rst new file mode 100644 index 000000000..fab10f02d --- /dev/null +++ b/documentation/source/plugins/songs.rst @@ -0,0 +1,46 @@ +.. _plugins-songs: + +:mod:`songs` Plugin +=================== + +.. automodule:: openlp.plugins.songs + :members: + +:mod:`SongsPlugin` Class +------------------------ + +.. autoclass:: openlp.plugins.songs.songsplugin.SongsPlugin + :members: + +:mod:`forms` Submodule +---------------------- + +.. automodule:: openlp.plugins.songs.forms + :members: + +:mod:`AuthorsForm` +^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.plugins.songs.forms.authorsdialog.Ui_AuthorsDialog + :members: + +.. autoclass:: openlp.plugins.songs.forms.authorsform.AuthorsForm + :members: + +:mod:`EditSongForm` +^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.plugins.songs.forms.editsongdialog.Ui_EditSongDialog + :members: + +.. autoclass:: openlp.plugins.songs.forms.editsongform.EditSongForm + :members: + +:mod:`EditVerseForm` +^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: openlp.plugins.songs.forms.editversedialog.Ui_EditVerseDialog + :members: + +.. autoclass:: openlp.plugins.songs.forms.editverseform.EditVerseForm + :members: diff --git a/openlp.pyw b/openlp.pyw index 7c7f8f373..f86fb3269 100755 --- a/openlp.pyw +++ b/openlp.pyw @@ -3,7 +3,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley, This program is free software; you can redistribute it and/or modify it under @@ -29,15 +31,7 @@ from openlp.core.lib import Receiver from openlp.core.resources import * from openlp.core.ui import MainWindow, SplashScreen -filename=u'openlp.log' log = logging.getLogger() -log.setLevel(logging.INFO) - -logfile = logging.handlers.RotatingFileHandler(filename ,maxBytes=200000, backupCount=5) -logfile.setLevel(logging.DEBUG) -logfile.setFormatter(logging.Formatter(u'%(asctime)s %(name)-15s %(levelname)-8s %(message)s')) - -log.addHandler(logfile) class OpenLP(QtGui.QApplication): """ @@ -78,22 +72,40 @@ class OpenLP(QtGui.QApplication): self.mainWindow.show() # now kill the splashscreen self.splash.finish(self.mainWindow) - sys.exit(app.exec_()) + sys.exit(self.exec_()) + def main(): - usage = "usage: %prog [options] arg1 arg2" + """ + The main function which parses command line options and then runs + the PyQt4 Application. + """ + # Set up command line options. + usage = u'Usage: %prog [options] [qt-options]' parser = OptionParser(usage=usage) - parser.add_option("-d", "--debug",dest="debug",action="store_true", - help="Switch on Debugging ") + parser.add_option("-d", "--debug", dest="debug", + action="store_true", help="set logging to DEBUG level") + # Set up logging + filename = u'openlp.log' + logfile = logging.handlers.RotatingFileHandler( + filename, maxBytes=200000, backupCount=5) + logfile.setFormatter( + logging.Formatter(u'%(asctime)s %(name)-15s %(levelname)-8s %(message)s')) + log.addHandler(logfile) + # Parse command line options and deal with them. (options, args) = parser.parse_args() if options.debug is not None: log.setLevel(logging.DEBUG) + else: + log.setLevel(logging.INFO) + # Now create and actually run the application. + app = OpenLP(sys.argv) + app.run() + if __name__ == u'__main__': """ Instantiate and run the application. """ - main() - app = OpenLP(sys.argv) #import cProfile - #cProfile.run("app.run()", "profile.out") - app.run() + #cProfile.run("main()", "profile.out") + main() diff --git a/openlp/__init__.py b/openlp/__init__.py index 6bcd6d97a..e70d1631d 100644 --- a/openlp/__init__.py +++ b/openlp/__init__.py @@ -1,6 +1,8 @@ """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under diff --git a/openlp/core/__init__.py b/openlp/core/__init__.py index e3518b436..dff015d30 100644 --- a/openlp/core/__init__.py +++ b/openlp/core/__init__.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under diff --git a/openlp/core/lib/__init__.py b/openlp/core/lib/__init__.py index 7d3087079..254982799 100644 --- a/openlp/core/lib/__init__.py +++ b/openlp/core/lib/__init__.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley, This program is free software; you can redistribute it and/or modify it under @@ -21,17 +23,51 @@ import types from PyQt4 import QtCore, QtGui def translate(context, text): + """ + A special shortcut method to wrap around the Qt4 translation functions. + This abstracts the translation procedure so that we can change it if at a + later date if necessary, without having to redo the whole of OpenLP. + + ``context`` + The translation context, used to give each string a context or a + namespace. + + ``text`` + The text to put into the translation tables for translation. + """ return QtGui.QApplication.translate(context, text, None, QtGui.QApplication.UnicodeUTF8) def file_to_xml(xmlfile): + """ + Open a file and return the contents of the file. + + ``xmlfile`` + The name of the file. + """ return open(xmlfile).read() def str_to_bool(stringvalue): + """ + Convert a string version of a boolean into a real boolean. + + ``stringvalue`` + The string value to examine and convert to a boolean type. + """ if stringvalue is True or stringvalue is False: return stringvalue return stringvalue.strip().lower() in (u'true', u'yes', u'y') def buildIcon(icon): + """ + Build a QIcon instance from an existing QIcon, a resource location, or a + physical file location. If the icon is a QIcon instance, that icon is + simply returned. If not, it builds a QIcon instance from the resource or + file name. + + ``icon`` + The icon to build. This can be a QIcon, a resource string in the form + ``:/resource/file.png``, or a file location like ``/path/to/file.png``. + """ ButtonIcon = None if type(icon) is QtGui.QIcon: ButtonIcon = icon @@ -59,6 +95,7 @@ def contextMenuSeparator(base): action.setSeparator(True) return action +from eventreceiver import Receiver from settingsmanager import SettingsManager from pluginconfig import PluginConfig from plugin import Plugin @@ -67,12 +104,10 @@ from settingstab import SettingsTab from mediamanageritem import MediaManagerItem from xmlrootclass import XmlRootClass from serviceitem import ServiceItem -from eventreceiver import Receiver from serviceitem import ServiceType from serviceitem import ServiceItem from toolbar import OpenLPToolbar -from songxmlhandler import SongXMLBuilder -from songxmlhandler import SongXMLParser +from songxmlhandler import SongXMLBuilder, SongXMLParser from themexmlhandler import ThemeXML from renderer import Renderer from rendermanager import RenderManager diff --git a/openlp/core/lib/eventreceiver.py b/openlp/core/lib/eventreceiver.py index 6c30f9970..75a09d955 100644 --- a/openlp/core/lib/eventreceiver.py +++ b/openlp/core/lib/eventreceiver.py @@ -24,8 +24,9 @@ from PyQt4 import QtCore class EventReceiver(QtCore.QObject): """ - Class to allow events to be passed from different parts of the system. - This is a private class and should not be used directly but via the Receiver class + Class to allow events to be passed from different parts of the + system. This is a private class and should not be used directly + but rather via the Receiver class. ``stop_import`` Stops the Bible Import @@ -36,13 +37,13 @@ class EventReceiver(QtCore.QObject): ``process_events`` Requests the Application to flush the events queue - ``{plugin}_add_service_item `` + ``{plugin}_add_service_item`` ask the plugin to push the selected items to the service item - ``update_themes `` + ``update_themes`` send out message with new themes - ``update_global_theme `` + ``update_global_theme`` Tell the components we have a new global theme ``load_song_list`` @@ -78,31 +79,57 @@ class EventReceiver(QtCore.QObject): log = logging.getLogger(u'EventReceiver') def __init__(self): + """ + Initialise the event receiver, calling the parent constructor. + """ QtCore.QObject.__init__(self) def send_message(self, event, msg=None): - log.debug(u'Event %s passed with payload %s' % (event, msg)) + """ + Emit a Qt signal. + + ``event`` + The event to that was sent. + + ``msg`` + Defaults to *None*. The message to send with the event. + """ self.emit(QtCore.SIGNAL(event), msg) + class Receiver(): """ - Class to allow events to be passed from different parts of the system. - This is a static wrapper around the EventReceiver class. - As there is only one instance of it in the systems the QT signal/slot architecture - can send messages across the system + Class to allow events to be passed from different parts of the + system. This is a static wrapper around the ``EventReceiver`` + class. As there is only one instance of it in the system the QT + signal/slot architecture can send messages across the system. - ``Send message`` - Receiver().send_message(u'<>', data) + To send a message: + ``Receiver().send_message(u'<>', data)`` - ``Receive Message`` - QtCore.QObject.connect(Receiver().get_receiver(),QtCore.SIGNAL(u'<>'),<>) + To receive a Message + ``QtCore.QObject.connect(Receiver().get_receiver(), QtCore.SIGNAL(u'<>'), <>)`` """ eventreceiver = EventReceiver() @staticmethod def send_message(event, msg=None): + """ + Sends a message to the messaging system. + + ``event`` + The event to send. + + ``msg`` + Defaults to *None*. The message to send with the event. + """ Receiver.eventreceiver.send_message(event, msg) @staticmethod def get_receiver(): + """ + Get the global ``eventreceiver`` instance. + """ return Receiver.eventreceiver + + diff --git a/openlp/core/lib/mediamanageritem.py b/openlp/core/lib/mediamanageritem.py index 12c1cca00..8ccc51919 100644 --- a/openlp/core/lib/mediamanageritem.py +++ b/openlp/core/lib/mediamanageritem.py @@ -31,28 +31,60 @@ class MediaManagerItem(QtGui.QWidget): MediaManagerItem is a helper widget for plugins. None of the following *need* to be used, feel free to override - them cmopletely in your plugin's implementation. Alternatively, call them from your - plugin before or after you've done etra things that you need to. + them cmopletely in your plugin's implementation. Alternatively, + call them from your plugin before or after you've done extra + things that you need to. - The plugin will be assigned an icon called u':/media/media_' + 'self.ShortPluginName + u'image.png' - which needs to be available in the main resources in order for them to work, you need to have setup + **Constructor Parameters** - self.TranslationContext - self.PluginTextShort # eg 'Image' for the image plugin - self.ConfigSection - where the items in the media manager are stored - this could potentially be self.PluginTextShort.lower() + ``parent`` + The parent widget. Usually this will be the *Media Manager* + itself. This needs to be a class descended from ``QWidget``. - self.OnNewPrompt=u'Select Image(s)' - self.OnNewFileMasks=u'Images (*.jpg *jpeg *.gif *.png *.bmp)' - assumes that the new action is to load a file. If not, override onnew + ``icon`` + Either a ``QIcon``, a resource path, or a file name. This is + the icon which is displayed in the *Media Manager*. - self.ListViewWithDnD_class - there is a base list class with DnD assigned to it (openlp.core.lib.BaseListWithDnD()) - each plugin needs to inherit a class from this and pass that *class* (not an instance) to here - via the ListViewWithDnD_class member + ``title`` + The title visible on the item in the *Media Manager*. - self.PreviewFunction - a function which returns a QImage to represent the item (a preview usually) - - no scaling required - that's done later - If this fn is not defined, a default will be used (treat the filename as an image) + **Member Variables** + + When creating a descendant class from this class for your plugin, + the following member variables should be set. + + ``self.TranslationContext`` + This sets the translation context of all the text in the + Media Manager item. + + ``self.PluginTextShort`` + The shortened name for the plugin, e.g. *'Image'* for the + image plugin. + + ``self.ConfigSection`` + The section in the configuration where the items in the media + manager are stored. This could potentially be + ``self.PluginTextShort.lower()``. + + ``self.OnNewPrompt`` + Defaults to *'Select Image(s)'*. + + ``self.OnNewFileMasks`` + Defaults to *'Images (*.jpg *jpeg *.gif *.png *.bmp)'*. This + assumes that the new action is to load a file. If not, you + need to override the ``OnNew`` method. + + ``self.ListViewWithDnD_class`` + This must be a **class**, not an object, descended from + ``openlp.core.lib.BaseListWithDnD`` that is not used in any + other part of OpenLP. + + ``self.PreviewFunction`` + This must be a method which returns a QImage to represent the + item (usually a preview). No scaling is required, that is + performed automatically by OpenLP when necessary. If this + method is not defined, a default will be used (treat the + filename as an image). """ global log @@ -83,12 +115,17 @@ class MediaManagerItem(QtGui.QWidget): self.initialise() def retranslateUi(self): + """ + This method is called automatically to provide OpenLP with the + opportunity to translate the ``MediaManagerItem`` to another + language. + """ pass def addToolbar(self): """ - A method to help developers easily add a toolbar to the media manager - item. + A method to help developers easily add a toolbar to the media + manager item. """ if self.Toolbar is None: self.Toolbar = OpenLPToolbar(self) @@ -97,9 +134,29 @@ class MediaManagerItem(QtGui.QWidget): def addToolbarButton(self, title, tooltip, icon, slot=None, objectname=None): """ A method to help developers easily add a button to the toolbar. + + ``title`` + The title of the button. + + ``tooltip`` + The tooltip to be displayed when the mouse hovers over the + button. + + ``icon`` + The icon of the button. This can be an instance of QIcon, or a + string cotaining either the absolute path to the image, or an + internal resource path starting with ':/'. + + ``slot`` + The method to call when the button is clicked. + + ``objectname`` + The name of the button. """ - # NB different order (when I broke this out, I wanted to not break compatability) - # but it makes sense for the icon to come before the tooltip (as you have to have an icon, but not neccesarily a tooltip) + # NB different order (when I broke this out, I didn't want to + # break compatability), but it makes sense for the icon to + # come before the tooltip (as you have to have an icon, but + # not neccesarily a tooltip) self.Toolbar.addToolbarButton(title, icon, tooltip, slot, objectname) def addToolbarSeparator(self): @@ -109,6 +166,11 @@ class MediaManagerItem(QtGui.QWidget): self.Toolbar.addSeparator() def setupUi(self): + """ + This method sets up the interface on the button. Plugin + developers use this to add and create toolbars, and the rest + of the interface of the media manager item. + """ # Add a toolbar self.addToolbar() # Create buttons for the toolbar @@ -189,6 +251,11 @@ class MediaManagerItem(QtGui.QWidget): QtCore.SIGNAL(u'doubleClicked(QModelIndex)'), self.onPreviewClick) def initialise(self): + """ + Implement this method in your descendent media manager item to + do any UI or other initialisation. This method is called + automatically. + """ pass def addHeaderBar(self): diff --git a/openlp/core/lib/plugin.py b/openlp/core/lib/plugin.py index 5f009c014..a338175a8 100644 --- a/openlp/core/lib/plugin.py +++ b/openlp/core/lib/plugin.py @@ -21,17 +21,13 @@ Place, Suite 330, Boston, MA 02111-1307 USA import logging from PyQt4 import QtCore -from openlp.core.lib import PluginConfig -# why does this not work??? -# from openlp.core.lib import Event, EventType -# so I have to do this??? -from eventreceiver import Receiver +from openlp.core.lib import PluginConfig, Receiver class Plugin(object): """ Base class for openlp plugins to inherit from. - Basic attributes are: + **Basic Attributes** ``name`` The name that should appear in the plugins list. @@ -49,7 +45,7 @@ class Plugin(object): ``log`` A log object used to log debugging messages. This is pre-instantiated. - Hook functions: + **Hook Functions** ``check_pre_conditions()`` Provides the Plugin with a handle to check if it can be loaded. @@ -201,7 +197,7 @@ class Plugin(object): def finalise(self): """ - Called by the plugin Manager to cleanup things + Called by the plugin Manager to cleanup things. """ pass diff --git a/openlp/core/lib/pluginconfig.py b/openlp/core/lib/pluginconfig.py index 241769751..d37cf96a0 100644 --- a/openlp/core/lib/pluginconfig.py +++ b/openlp/core/lib/pluginconfig.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008 -2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -19,6 +21,7 @@ Place, Suite 330, Boston, MA 02111-1307 USA """ import os + from openlp.core.utils import ConfigHelper class PluginConfig(object): diff --git a/openlp/core/lib/pluginmanager.py b/openlp/core/lib/pluginmanager.py index c1eaf79fb..fe6bc20cf 100644 --- a/openlp/core/lib/pluginmanager.py +++ b/openlp/core/lib/pluginmanager.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008 - 2009 Martin Thompson, Tim Bentley, This program is free software; you can redistribute it and/or modify it under @@ -52,7 +54,8 @@ class PluginManager(object): def find_plugins(self, dir, plugin_helpers): """ - Scan the directory dir for objects inheriting from ``openlp.plugin``. + Scan the directory ``dir`` for objects inheriting from the ``Plugin`` + class. ``dir`` The directory to scan. diff --git a/openlp/core/lib/renderer.py b/openlp/core/lib/renderer.py index 7a818b03c..bb3e28e93 100644 --- a/openlp/core/lib/renderer.py +++ b/openlp/core/lib/renderer.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under diff --git a/openlp/core/lib/rendermanager.py b/openlp/core/lib/rendermanager.py index c8516eef8..14d7b4be0 100644 --- a/openlp/core/lib/rendermanager.py +++ b/openlp/core/lib/rendermanager.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008 - 2009Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -31,23 +33,23 @@ class RenderManager(object): Class to pull all Renderer interactions into one place. The plugins will call helper methods to do the rendering but this class will provide display defense code. + + ``theme_manager`` + The ThemeManager instance, used to get the current theme details. + + ``screen_list`` + The list of screens available. + + ``screen_number`` + Defaults to *0*. The index of the output/display screen. """ global log - log=logging.getLogger(u'RenderManager') + log = logging.getLogger(u'RenderManager') log.info(u'RenderManager Loaded') def __init__(self, theme_manager, screen_list, screen_number=0): """ Initialise the render manager. - - ``theme_manager`` - The ThemeManager instance, used to get the current theme details. - - ``screen_list`` - The list of screens available. - - ``screen_number`` - Defaults to *0*. The index of the output/display screen. """ log.debug(u'Initilisation started') self.screen_list = screen_list diff --git a/openlp/core/lib/serviceitem.py b/openlp/core/lib/serviceitem.py index eba0372b2..d6da91850 100644 --- a/openlp/core/lib/serviceitem.py +++ b/openlp/core/lib/serviceitem.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -37,7 +39,7 @@ class ServiceItem(object): compositor. """ global log - log=logging.getLogger(u'ServiceItem') + log = logging.getLogger(u'ServiceItem') log.info(u'Service Item created') def __init__(self, hostplugin=None): diff --git a/openlp/core/lib/settingsmanager.py b/openlp/core/lib/settingsmanager.py index c71453970..ac53e652b 100644 --- a/openlp/core/lib/settingsmanager.py +++ b/openlp/core/lib/settingsmanager.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -20,8 +22,9 @@ Place, Suite 330, Boston, MA 02111-1307 USA class SettingsManager(object): """ - Class to control the size of the UI components so they size correctly - This class is created by the main window and then calculates the size of individual components + Class to control the size of the UI components so they size correctly. + This class is created by the main window and then calculates the size of + individual components. """ def __init__(self, screen): self.screen = screen[0] diff --git a/openlp/core/lib/settingstab.py b/openlp/core/lib/settingstab.py index 4e59f6468..0a3b6145d 100644 --- a/openlp/core/lib/settingstab.py +++ b/openlp/core/lib/settingstab.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -19,6 +21,7 @@ Place, Suite 330, Boston, MA 02111-1307 USA """ from PyQt4 import QtCore, QtGui + from openlp.core.lib import PluginConfig class SettingsTab(QtGui.QWidget): diff --git a/openlp/core/lib/songxmlhandler.py b/openlp/core/lib/songxmlhandler.py index 9cb0bb4e9..d66b11da9 100644 --- a/openlp/core/lib/songxmlhandler.py +++ b/openlp/core/lib/songxmlhandler.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley, Carsten Tinggaard This program is free software; you can redistribute it and/or modify it under @@ -16,26 +18,25 @@ PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -from xml.dom.minidom import Document -from xml.etree.ElementTree import ElementTree, XML, dump - - - - - - - - - - """ import logging from xml.dom.minidom import Document from xml.etree.ElementTree import ElementTree, XML, dump -class SongXMLBuilder(): +class SongXMLBuilder(object): """ This class builds the XML used to describe songs. + + The basic XML looks like this:: + + + + + + + + + """ def __init__(self): """ @@ -97,9 +98,21 @@ class SongXMLBuilder(): """ return self.song_xml.toxml(u'utf-8') -class SongXMLParser(): + +class SongXMLParser(object): """ A class to read in and parse a song's XML. + + The basic XML looks like this:: + + + + + + + + + """ global log log = logging.getLogger(u'SongXMLParser') diff --git a/openlp/core/lib/themexmlhandler.py b/openlp/core/lib/themexmlhandler.py index 0ee295e72..3e6ed41de 100644 --- a/openlp/core/lib/themexmlhandler.py +++ b/openlp/core/lib/themexmlhandler.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley, Carsten Tinggaard This program is free software; you can redistribute it and/or modify it under diff --git a/openlp/core/lib/toolbar.py b/openlp/core/lib/toolbar.py index 73835b8f3..c5511236b 100644 --- a/openlp/core/lib/toolbar.py +++ b/openlp/core/lib/toolbar.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2009 Raoul Snyman + Portions copyright (c) 2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -109,9 +111,21 @@ class OpenLPToolbar(QtGui.QToolBar): return QtGui.QIcon() def makeWidgetsInvisible(self, widgets): + """ + Hide a set of widgets. + + ``widgets`` + The list of names of widgets to be hidden. + """ for widget in widgets: self.actions[widget].setVisible(False) def makeWidgetsVisible(self, widgets): + """ + Show a set of widgets. + + ``widgets`` + The list of names of widgets to be shown. + """ for widget in widgets: self.actions[widget].setVisible(True) diff --git a/openlp/core/lib/xmlrootclass.py b/openlp/core/lib/xmlrootclass.py index 3cd559f62..677a426f0 100644 --- a/openlp/core/lib/xmlrootclass.py +++ b/openlp/core/lib/xmlrootclass.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008 Martin Thompson, Tim Bentley, Carsten Tinggaard This program is free software; you can redistribute it and/or modify it under diff --git a/openlp/plugins/songs/songsplugin.py b/openlp/plugins/songs/songsplugin.py index 598e32d06..d8d297f41 100644 --- a/openlp/plugins/songs/songsplugin.py +++ b/openlp/plugins/songs/songsplugin.py @@ -28,12 +28,22 @@ from openlp.plugins.songs.forms import OpenLPImportForm, OpenSongExportForm, \ OpenSongImportForm, OpenLPExportForm class SongsPlugin(Plugin): + """ + This is the number 1 plugin, if importance were placed on any + plugins. This plugin enables the user to create, edit and display + songs. Songs are divided into verses, and the verse order can be + specified. Authors, topics and song books can be assigned to songs + as well. + """ global log log = logging.getLogger(u'SongsPlugin') log.info(u'Song Plugin loaded') def __init__(self, plugin_helpers): + """ + Create and set up the Songs plugin. + """ # Call the parent constructor Plugin.__init__(self, u'Songs', u'1.9.0', plugin_helpers) self.weight = -10 @@ -48,11 +58,22 @@ class SongsPlugin(Plugin): QtGui.QIcon.Normal, QtGui.QIcon.Off) def get_media_manager_item(self): - # Create the MediaManagerItem object + """ + Create the MediaManagerItem object, which is displaed in the + Media Manager. + """ self.media_item = SongMediaItem(self, self.icon, 'Songs') return self.media_item def add_import_menu_item(self, import_menu): + """ + Give the Songs plugin the opportunity to add items to the + **Import** menu. + + ``import_menu`` + The actual **Import** menu item, so that your actions can + use it as their parent. + """ self.ImportSongMenu = QtGui.QMenu(import_menu) self.ImportSongMenu.setObjectName(u'ImportSongMenu') self.ImportOpenSongItem = QtGui.QAction(import_menu) @@ -88,6 +109,14 @@ class SongsPlugin(Plugin): QtCore.SIGNAL(u'triggered()'), self.onImportOpenSongItemClick) def add_export_menu_item(self, export_menu): + """ + Give the Songs plugin the opportunity to add items to the + **Export** menu. + + ``export_menu`` + The actual **Export** menu item, so that your actions can + use it as their parent. + """ self.ExportSongMenu = QtGui.QMenu(export_menu) self.ExportSongMenu.setObjectName(u'ExportSongMenu') self.ExportOpenSongItem = QtGui.QAction(export_menu)