raoul
/
openlp
forked from openlp/openlp
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Some updates to the documentation: 

- Added some more classes to the rST files.
- Fixed up some docstrings to proper rST.
This commit is contained in:
Raoul Snyman 2010-10-10 23:13:10 +02:00
parent bf7df829d0
commit 3a8b33a5ff
6 changed files with 217 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
documentation/source/conf.py
View File

@ -17,7 +17,7 @@ import sys
# If extensions (or modules to document with autodoc) are in another directory, # If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the # add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here. # documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.append(os.path.abspath(os.path.join('..', '..'))) sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
# -- General configuration ----------------------------------------------------- # -- General configuration -----------------------------------------------------

6
documentation/source/core/lib.rst
View File

@ -60,12 +60,6 @@
.. autoclass:: openlp.core.lib.settingstab.SettingsTab .. autoclass:: openlp.core.lib.settingstab.SettingsTab
:members: :members:
:mod:`ThemeXML`
---------------
.. autoclass:: openlp.core.lib.themexmlhandler.ThemeXML
:members:
:mod:`OpenLPToolbar` :mod:`OpenLPToolbar`
-------------------- --------------------

163
documentation/source/plugins/songs.rst
View File

@ -6,8 +6,8 @@
.. automodule:: openlp.plugins.songs .. automodule:: openlp.plugins.songs
:members: :members:
:mod:`SongsPlugin` Class :class:`SongsPlugin` Class
------------------------ --------------------------
.. autoclass:: openlp.plugins.songs.songsplugin.SongsPlugin .. autoclass:: openlp.plugins.songs.songsplugin.SongsPlugin
:members: :members:
@ -18,8 +18,8 @@
.. automodule:: openlp.plugins.songs.forms .. automodule:: openlp.plugins.songs.forms
:members: :members:
:mod:`AuthorsForm` :class:`AuthorsForm`
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
.. autoclass:: openlp.plugins.songs.forms.authorsdialog.Ui_AuthorsDialog .. autoclass:: openlp.plugins.songs.forms.authorsdialog.Ui_AuthorsDialog
:members: :members:
@ -27,8 +27,8 @@
.. autoclass:: openlp.plugins.songs.forms.authorsform.AuthorsForm .. autoclass:: openlp.plugins.songs.forms.authorsform.AuthorsForm
:members: :members:
:mod:`EditSongForm` :class:`EditSongForm`
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: openlp.plugins.songs.forms.editsongdialog.Ui_EditSongDialog .. autoclass:: openlp.plugins.songs.forms.editsongdialog.Ui_EditSongDialog
:members: :members:
@ -36,11 +36,158 @@
.. autoclass:: openlp.plugins.songs.forms.editsongform.EditSongForm .. autoclass:: openlp.plugins.songs.forms.editsongform.EditSongForm
:members: :members:
:mod:`EditVerseForm` :class:`EditVerseForm`
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: openlp.plugins.songs.forms.editversedialog.Ui_EditVerseDialog .. autoclass:: openlp.plugins.songs.forms.editversedialog.Ui_EditVerseDialog
:members: :members:
.. autoclass:: openlp.plugins.songs.forms.editverseform.EditVerseForm .. autoclass:: openlp.plugins.songs.forms.editverseform.EditVerseForm
:members: :members:
:class:`SongBookForm`
^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: openlp.plugins.songs.forms.songbookdialog.Ui_SongBookDialog
:members:
.. autoclass:: openlp.plugins.songs.forms.songbookform.SongBookForm
:members:
:class:`SongImportForm`
^^^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: openlp.plugins.songs.forms.songimportwizard.Ui_SongImportWizard
:members:
.. autoclass:: openlp.plugins.songs.forms.songimportform.ImportWizardForm
:members:
:class:`SongMaintenanceForm`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: openlp.plugins.songs.forms.songmaintenancedialog.Ui_SongMaintenanceDialog
:members:
.. autoclass:: openlp.plugins.songs.forms.songmaintenanceform.SongMaintenanceForm
:members:
:class:`TopicsForm`
^^^^^^^^^^^^^^^^^^^
.. autoclass:: openlp.plugins.songs.forms.topicsdialog.Ui_TopicsDialog
:members:
.. autoclass:: openlp.plugins.songs.forms.topicsform.TopicsForm
:members:
:mod:`lib` Submodule
--------------------
.. automodule:: openlp.plugins.songs.lib
:members:
:mod:`cclifileimport` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.cclifileimport
:members:
.. autoclass:: openlp.plugins.songs.lib.cclifileimport.CCLIFileImportError
:members:
:mod:`db` Submodule
^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.db
:members:
:mod:`ewimport` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.ewimport
:members:
.. autoclass:: openlp.plugins.songs.lib.ewimport.FieldDescEntry
:members:
:mod:`importer` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.importer
:members:
:mod:`mediaitem` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.mediaitem
:members:
.. autoclass:: openlp.plugins.songs.lib.mediaitem.SongListView
:members:
:mod:`olp1import` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.olp1import
:members:
:mod:`olpimport` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.olpimport
:members:
:mod:`oooimport` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.oooimport
:members:
:mod:`opensongimport` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.opensongimport
:members:
:mod:`sofimport` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.sofimport
:members:
:mod:`songbeamerimport` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.songbeamerimport
:members:
:mod:`songimport` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.songimport
:members:
:mod:`songstab` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.songstab
:members:
:mod:`wowimport` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.wowimport
:members:
:mod:`songxml` Submodule
^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.songxml
:members:
:mod:`xml` Submodule
^^^^^^^^^^^^^^^^^^^^
.. automodule:: openlp.plugins.songs.lib.xml
:members:

63
openlp/plugins/songs/lib/cclifileimport.py
View File

@ -38,9 +38,9 @@ class CCLIFileImportError(Exception):
class CCLIFileImport(SongImport): class CCLIFileImport(SongImport):
""" """
The :class:`CCLIFileImport` class provides OpenLP with the The :class:`CCLIFileImport` class provides OpenLP with the ability to
ability to import CCLI SongSelect song files in both .txt and import CCLI SongSelect song files in both .txt and .usr formats.
.usr formats. See http://www.ccli.com See http://www.ccli.com/ for more details.
""" """
def __init__(self, manager, **kwargs): def __init__(self, manager, **kwargs):
@ -49,6 +49,7 @@ class CCLIFileImport(SongImport):
``manager`` ``manager``
The song manager for the running OpenLP installation. The song manager for the running OpenLP installation.
``filenames`` ``filenames``
The files to be imported. The files to be imported.
""" """
@ -97,7 +98,7 @@ class CCLIFileImport(SongImport):
def do_import_usr_file(self, textList): def do_import_usr_file(self, textList):
""" """
The :method:`do_import_usr_file` method provides OpenLP The :func:`do_import_usr_file` method provides OpenLP
with the ability to import CCLI SongSelect songs in with the ability to import CCLI SongSelect songs in
*USR* file format *USR* file format
@ -105,6 +106,7 @@ class CCLIFileImport(SongImport):
An array of strings containing the usr file content. An array of strings containing the usr file content.
**SongSelect .usr file format** **SongSelect .usr file format**
``[File]`` ``[File]``
USR file format first line USR file format first line
``Type=`` ``Type=``
@ -140,6 +142,7 @@ class CCLIFileImport(SongImport):
Contains the songs various lyrics in order as shown by the Contains the songs various lyrics in order as shown by the
*Fields* description *Fields* description
e.g. *Words=Above all powers....* [/n = CR, /n/t = CRLF] e.g. *Words=Above all powers....* [/n = CR, /n/t = CRLF]
""" """
log.debug(u'USR file text: %s', textList) log.debug(u'USR file text: %s', textList)
lyrics = [] lyrics = []
@ -191,48 +194,32 @@ class CCLIFileImport(SongImport):
def do_import_txt_file(self, textList): def do_import_txt_file(self, textList):
""" """
The :method:`do_import_txt_file` method provides OpenLP The :func:`do_import_txt_file` method provides OpenLP
with the ability to import CCLI SongSelect songs in with the ability to import CCLI SongSelect songs in
*TXT* file format *TXT* file format
``textList`` ``textList``
An array of strings containing the txt file content. An array of strings containing the txt file content.
**SongSelect .txt file format** SongSelect .txt file format::
``Song Title`` Song Title # Contains the song title
Contains the song title <Empty line>
Verse type and number # e.g. Verse 1, Chorus 1
<Empty line> Verse lyrics
<Empty line>
``Title of following verse/chorus and number`` <Empty line>
e.g. Verse 1, Chorus 1 Verse type and number (repeats)
Verse lyrics
``Verse/Chorus lyrics`` <Empty line>
<Empty line>
<Empty line> Song CCLI number # e.g. CCLI Number (e.g.CCLI-Liednummer: 2672885)
Song copyright # e.g. © 1999 Integrity's Hosanna! Music | LenSongs Publishing
<Empty line> Song authors # e.g. Lenny LeBlanc | Paul Baloche
Licencing info # e.g. For use solely with the SongSelect Terms of Use.
``Title of next verse/chorus (repeats)``
``Verse/Chorus lyrics``
<Empty line>
<Empty line>
``Song CCLI Number``
e.g. CCLI Number (e.g.CCLI-Liednummer: 2672885)
``Song Copyright``
e.g. © 1999 Integrity's Hosanna! Music | LenSongs Publishing
``Song Authors``
e.g. Lenny LeBlanc | Paul Baloche
``Licencing info``
e.g. For use solely with the SongSelect Terms of Use.
All rights Reserved. www.ccli.com All rights Reserved. www.ccli.com
``CCLI Licence number of user`` CCLI Licence number of user # e.g. CCL-Liedlizenznummer: 14 / CCLI License No. 14
e.g. CCL-Liedlizenznummer: 14 / CCLI License No. 14
""" """
log.debug(u'TXT file text: %s', textList) log.debug(u'TXT file text: %s', textList)
self.set_defaults() self.set_defaults()

20
openlp/plugins/songs/lib/songxml.py
View File

@ -282,11 +282,9 @@ class Song(object):
def get_author_list(self, asOneString = True): def get_author_list(self, asOneString = True):
"""Return the list of authors as a string """Return the list of authors as a string
asOneString ``asOneString``
True -- string: If ``True``, returns 'John Newton, A Parker'. If ``False``, returns
'John Newton, A Parker' [u'John Newton', u'A Parker']
False -- list of strings
['John Newton', u'A Parker']
""" """
if asOneString: if asOneString:
res = self._assure_string(self.author_list) res = self._assure_string(self.author_list)
@ -297,7 +295,8 @@ class Song(object):
def set_author_list(self, author_list): def set_author_list(self, author_list):
"""Set the author_list """Set the author_list
author_list -- a string or list of strings ``author_list``
a string or list of strings
""" """
if author_list is None: if author_list is None:
self.author_list = None self.author_list = None
@ -307,11 +306,9 @@ class Song(object):
def get_category_array(self, asOneString = True): def get_category_array(self, asOneString = True):
"""Return the list of categories as a string """Return the list of categories as a string
asOneString ``asOneString``
True -- string: If ``True``, returns 'Hymn, Gospel'. If ``False``, returns
'Hymn, Gospel' [u'Hymn', u'Gospel']
False -- list of strings
['Hymn', u'Gospel']
""" """
if asOneString: if asOneString:
res = self._assure_string(self.category_array) res = self._assure_string(self.category_array)
@ -381,6 +378,7 @@ class Song(object):
properties properties
slideNumber -- 1 .. numberOfSlides slideNumber -- 1 .. numberOfSlides
Returns a list as: Returns a list as:
[theme_name (string), [theme_name (string),
title (string), title (string),

55
openlp/plugins/songs/lib/wowimport.py
View File

@ -24,7 +24,7 @@
# Temple Place, Suite 330, Boston, MA 02111-1307 USA # # Temple Place, Suite 330, Boston, MA 02111-1307 USA #
############################################################################### ###############################################################################
""" """
The :mod:`wowimport` module provides the functionality for importing Words of The :mod:`wowimport` module provides the functionality for importing Words of
Worship songs into the OpenLP database. Worship songs into the OpenLP database.
""" """
import os import os
@ -38,19 +38,18 @@ log = logging.getLogger(__name__)
class WowImport(SongImport): class WowImport(SongImport):
""" """
The :class:`WowImport` class provides the ability to import song files from The :class:`WowImport` class provides the ability to import song files from
Words of Worship. Words of Worship.
Words Of Worship Song File Format **Words Of Worship Song File Format:**
`````````````````````````````````
The Words Of Worship song file format is as follows: The Words Of Worship song file format is as follows:
* The song title is the file name minus the extension. * The song title is the file name minus the extension.
* The song has a header, a number of blocks, followed by footer containing * The song has a header, a number of blocks, followed by footer containing
the author and the copyright. the author and the copyright.
* A block can be a verse, chorus or bridge. * A block can be a verse, chorus or bridge.
File Header: File Header:
Bytes are counted from one, i.e. the first byte is byte 1. These bytes, Bytes are counted from one, i.e. the first byte is byte 1. These bytes,
up to the 56 byte, can change but no real meaning has been found. The up to the 56 byte, can change but no real meaning has been found. The
@ -65,29 +64,29 @@ class WowImport(SongImport):
Each block ends with 4 bytes, the first of which defines what type of Each block ends with 4 bytes, the first of which defines what type of
block it is, and the rest which are null bytes: block it is, and the rest which are null bytes:
* ``NUL`` (\x00) - Verse * ``NUL`` (0x00) - Verse
* ``SOH`` (\x01) - Chorus * ``SOH`` (0x01) - Chorus
* ``STX`` (\x02) - Bridge * ``STX`` (0x02) - Bridge
Blocks are seperated by two bytes. The first byte is ``SOH`` (\x01), Blocks are seperated by two bytes. The first byte is 0x01, and the
and the second byte is ``€`` (\x80). second byte is 0x80.
Lines: Lines:
Each line starts with a byte which specifies how long that line is, Each line starts with a byte which specifies how long that line is,
the line text, and ends with a null byte. the line text, and ends with a null byte.
Footer: Footer:
The footer follows on after the last block, the first byte specifies The footer follows on after the last block, the first byte specifies
the length of the author text, followed by the author text, if the length of the author text, followed by the author text, if
this byte is null, then there is no author text. The byte after the this byte is null, then there is no author text. The byte after the
author text specifies the length of the copyright text, followed author text specifies the length of the copyright text, followed
by the copyright text. by the copyright text.
The file is ended with four null bytes. The file is ended with four null bytes.
Valid extensions for a Words of Worship song file are: Valid extensions for a Words of Worship song file are:
* .wsg * .wsg
* .wow-song * .wow-song
""" """
@ -111,7 +110,7 @@ class WowImport(SongImport):
""" """
Recieve a single file, or a list of files to import. Recieve a single file, or a list of files to import.
""" """
if isinstance(self.import_source, list): if isinstance(self.import_source, list):
self.import_wizard.importProgressBar.setMaximum( self.import_wizard.importProgressBar.setMaximum(
len(self.import_source)) len(self.import_source))
@ -127,14 +126,14 @@ class WowImport(SongImport):
if self.songData.read(19) != u'WoW File\nSong Words': if self.songData.read(19) != u'WoW File\nSong Words':
continue continue
# Seek to byte which stores number of blocks in the song # Seek to byte which stores number of blocks in the song
self.songData.seek(56) self.songData.seek(56)
self.no_of_blocks = ord(self.songData.read(1)) self.no_of_blocks = ord(self.songData.read(1))
# Seek to the beging of the first block # Seek to the beging of the first block
self.songData.seek(82) self.songData.seek(82)
for block in range(self.no_of_blocks): for block in range(self.no_of_blocks):
self.lines_to_read = ord(self.songData.read(1)) self.lines_to_read = ord(self.songData.read(1))
# Skip 3 nulls to the beginnig of the 1st line # Skip 3 nulls to the beginnig of the 1st line
self.songData.seek(3, os.SEEK_CUR) self.songData.seek(3, os.SEEK_CUR)
self.block_text = u'' self.block_text = u''
while self.lines_to_read: while self.lines_to_read:
self.length_of_line = ord(self.songData.read(1)) self.length_of_line = ord(self.songData.read(1))
@ -148,7 +147,7 @@ class WowImport(SongImport):
self.block_type = BLOCK_TYPES[ord(self.songData.read(1))] self.block_type = BLOCK_TYPES[ord(self.songData.read(1))]
# Skip 3 nulls at the end of the block # Skip 3 nulls at the end of the block
self.songData.seek(3, os.SEEK_CUR) self.songData.seek(3, os.SEEK_CUR)
# Blocks are seperated by 2 bytes, skip them, but not if # Blocks are seperated by 2 bytes, skip them, but not if
# this is the last block! # this is the last block!
if (block + 1) < self.no_of_blocks: if (block + 1) < self.no_of_blocks:
self.songData.seek(2, os.SEEK_CUR) self.songData.seek(2, os.SEEK_CUR)
@ -170,4 +169,4 @@ class WowImport(SongImport):
self.import_wizard.incrementProgressBar( self.import_wizard.incrementProgressBar(
"Importing %s" % (self.file_name)) "Importing %s" % (self.file_name))
return True return True