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

Fix docstrings and update documentation.

This commit is contained in:
Raoul Snyman 2011-02-10 07:25:08 +02:00
parent f80edf2092
commit 8abfd2ce14
6 changed files with 105 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
documentation/api/source/openlp.rst
View File

@ -1,7 +0,0 @@
.. _openlp:
:mod:`openlp` Module
====================
.. automodule:: openlp
:members:

2
documentation/api/source/plugins/bibles.rst
View File

@ -18,7 +18,7 @@ Forms
.. automodule:: openlp.plugins.bibles.forms
:members:
.. autoclass:: openlp.plugins.bibles.forms.importwizardform.ImportWizardForm
.. autoclass:: openlp.plugins.bibles.forms.bibleimportform.BibleImportForm
:members:
Helper Classes & Functions

2
openlp/core/ui/servicemanager.py
View File

@ -461,7 +461,7 @@ class ServiceManager(QtGui.QWidget):
def saveFileAs(self):
"""
Get a file name and then call :function:`ServiceManager.saveFile` to
Get a file name and then call :func:`ServiceManager.saveFile` to
save the file.
"""
fileName = unicode(QtGui.QFileDialog.getSaveFileName(self.mainwindow,

134
openlp/plugins/bibles/lib/__init__.py
View File

@ -62,69 +62,90 @@ def get_reference_match(match_type):
def parse_reference(reference):
"""
This is the next generation über-awesome function that takes a person's
typed in string and converts it to a reference list, a list of references to
be queried from the Bible database files.
typed in string and converts it to a list of references to be queried from
the Bible database files.
This is a user manual like description, how the references are working.
``reference``
A string. The Bible reference to parse.
- Each reference starts with the book name. A chapter name is manditory.
``John 3`` refers to Gospel of John chapter 3
- A reference range can be given after a range separator.
``John 3-5`` refers to John chapters 3 to 5
- Single verses can be addressed after a verse separator
``John 3:16`` refers to John chapter 3 verse 16
``John 3:16-4:3`` refers to John chapter 3 verse 16 to chapter 4 verse 3
- After a verse reference all further single values are treat as verse in
the last selected chapter.
``John 3:16-18`` refers to John chapter 3 verses 16 to 18
- After a list separator it is possible to refer to additional verses. They
are build analog to the first ones. This way it is possible to define each
number of verse references. It is not possible to refer to verses in
additional books.
``John 3:16,18`` refers to John chapter 3 verses 16 and 18
``John 3:16-18,20`` refers to John chapter 3 verses 16 to 18 and 20
``John 3:16-18,4:1`` refers to John chapter 3 verses 16 to 18 and
chapter 3 verse 1
- If there is a range separator without further verse declaration the last
refered chapter is addressed until the end.
``range_string`` is a regular expression which matches for verse range
declarations:
1. ``(?:(?P<from_chapter>[0-9]+)%(sep_v)s)?``
It starts with a optional chapter reference ``from_chapter`` followed by
a verse separator.
2. ``(?P<from_verse>[0-9]+)``
The verse reference ``from_verse`` is manditory
3. ``(?P<range_to>%(sep_r)s(?:`` ... ``|%(sep_e)s)?)?``
A ``range_to`` declaration is optional. It starts with a range separator
and contains optional a chapter and verse declaration or a end
separator.
4. ``(?:(?P<to_chapter>[0-9]+)%(sep_v)s)?``
The ``to_chapter`` reference with separator is equivalent to group 1.
5. ``(?P<to_verse>[0-9]+)``
The ``to_verse`` reference is equivalent to group 2.
The full reference is matched against get_reference_match(u'full'). This
regular expression looks like this:
1. ``^\s*(?!\s)(?P<book>[\d]*[^\d]+)(?<!\s)\s*``
The ``book`` group starts with the first non-whitespace character. There
are optional leading digits followed by non-digits. The group ends
before the whitspace in front of the next digit.
2. ``(?P<ranges>(?:`` + range_string + ``(?:%(sep_l)s|(?=\s*$)))+)\s*$``
The second group contains all ``ranges``. This can be multiple
declarations of a range_string separated by a list separator.
Returns ``None`` or a reference list.
The reference list is a list of tuples, with each tuple structured like
this::
(book, chapter, from_verse, to_verse)
For example::
[(u'John', 3, 16, 18), (u'John', 4, 1, 1)]
``reference``
The bible reference to parse.
**Reference string details:**
Each reference starts with the book name and a chapter number. These are
both mandatory.
* ``John 3`` refers to Gospel of John chapter 3
A reference range can be given after a range separator.
* ``John 3-5`` refers to John chapters 3 to 5
Single verses can be addressed after a verse separator.
* ``John 3:16`` refers to John chapter 3 verse 16
* ``John 3:16-4:3`` refers to John chapter 3 verse 16 to chapter 4 verse 3
After a verse reference all further single values are treat as verse in
the last selected chapter.
* ``John 3:16-18`` refers to John chapter 3 verses 16 to 18
After a list separator it is possible to refer to additional verses. They
are build analog to the first ones. This way it is possible to define each
number of verse references. It is not possible to refer to verses in
additional books.
* ``John 3:16,18`` refers to John chapter 3 verses 16 and 18
* ``John 3:16-18,20`` refers to John chapter 3 verses 16 to 18 and 20
* ``John 3:16-18,4:1`` refers to John chapter 3 verses 16 to 18 and
chapter 4 verse 1
If there is a range separator without further verse declaration the last
refered chapter is addressed until the end.
``range_string`` is a regular expression which matches for verse range
declarations:
``(?:(?P<from_chapter>[0-9]+)%(sep_v)s)?``
It starts with a optional chapter reference ``from_chapter`` followed by
a verse separator.
``(?P<from_verse>[0-9]+)``
The verse reference ``from_verse`` is manditory
``(?P<range_to>%(sep_r)s(?:`` ... ``|%(sep_e)s)?)?``
A ``range_to`` declaration is optional. It starts with a range separator
and contains optional a chapter and verse declaration or a end
separator.
``(?:(?P<to_chapter>[0-9]+)%(sep_v)s)?``
The ``to_chapter`` reference with separator is equivalent to group 1.
``(?P<to_verse>[0-9]+)``
The ``to_verse`` reference is equivalent to group 2.
The full reference is matched against get_reference_match(u'full'). This
regular expression looks like this:
``^\s*(?!\s)(?P<book>[\d]*[^\d]+)(?<!\s)\s*``
The ``book`` group starts with the first non-whitespace character. There
are optional leading digits followed by non-digits. The group ends
before the whitspace in front of the next digit.
``(?P<ranges>(?:`` + range_string + ``(?:%(sep_l)s|(?=\s*$)))+)\s*$``
The second group contains all ``ranges``. This can be multiple
declarations of a range_string separated by a list separator.
Returns None or a reference list.
"""
log.debug(u'parse_reference("%s")', reference)
match = get_reference_match(u'full').match(reference)
@ -194,7 +215,7 @@ def parse_reference(reference):
class SearchResults(object):
"""
Encapsulate a set of search results. This is Bible-type independent.
Encapsulate a set of search results. This is Bible-type independent.
"""
def __init__(self, book, chapter, verselist):
"""
@ -207,7 +228,8 @@ class SearchResults(object):
The chapter of the book.
``verselist``
The list of verses for this reading
The list of verses for this reading.
"""
self.book = book
self.chapter = chapter

4
openlp/plugins/songs/lib/songimport.py
View File

@ -50,6 +50,7 @@ class SongImport(QtCore.QObject):
``manager``
An instance of a SongManager, through which all database access is
performed.
"""
self.manager = manager
self.stop_import_flag = False
@ -199,7 +200,7 @@ class SongImport(QtCore.QObject):
def add_verse(self, versetext, versetag=u'V', lang=None):
"""
Add a verse. This is the whole verse, lines split by \n. It will also
Add a verse. This is the whole verse, lines split by \\n. It will also
attempt to detect duplicates. In this case it will just add to the verse
order.
@ -212,6 +213,7 @@ class SongImport(QtCore.QObject):
``lang``
The language code (ISO-639) of the verse, for example *en* or *de*.
"""
for (oldversetag, oldverse, oldlang) in self.verses:
if oldverse.strip() == versetext.strip():

43
openlp/plugins/songs/lib/xml.py
View File

@ -26,7 +26,7 @@
"""
The :mod:`xml` module provides the XML functionality.
The basic XML for storing the lyrics in the song database is of the format::
The basic XML for storing the lyrics in the song database looks like this::
<?xml version="1.0" encoding="UTF-8"?>
<song version="1.0">
@ -38,7 +38,7 @@ The basic XML for storing the lyrics in the song database is of the format::
</song>
The XML of `OpenLyrics <http://openlyrics.info/>`_ songs is of the format::
The XML of an `OpenLyrics <http://openlyrics.info/>`_ song looks like this::
<song xmlns="http://openlyrics.info/namespace/2009/song"
version="0.7"
@ -86,7 +86,7 @@ class SongXML(object):
def add_verse_to_lyrics(self, type, number, content, lang=None):
"""
Add a verse to the *<lyrics>* tag.
Add a verse to the ``<lyrics>`` tag.
``type``
A string denoting the type of verse. Possible values are "V",
@ -158,59 +158,60 @@ class OpenLyrics(object):
to/from a song.
As OpenLyrics has a rich set of different features, we cannot support them
all. The following features are supported by the :class:`OpenLyrics`::
all. The following features are supported by the :class:`OpenLyrics` class:
*<authors>*
``<authors>``
OpenLP does not support the attribute *type* and *lang*.
*<chord>*
``<chord>``
This property is not supported.
*<comments>*
The *<comments>* property is fully supported. But comments in lyrics
``<comments>``
The ``<comments>`` property is fully supported. But comments in lyrics
are not supported.
*<copyright>*
``<copyright>``
This property is fully supported.
*<customVersion>*
``<customVersion>``
This property is not supported.
*<key>*
``<key>``
This property is not supported.
*<keywords>*
``<keywords>``
This property is not supported.
*<lines>*
``<lines>``
The attribute *part* is not supported.
*<publisher>*
``<publisher>``
This property is not supported.
*<songbooks>*
``<songbooks>``
As OpenLP does only support one songbook, we cannot consider more than
one songbook.
*<tempo>*
``<tempo>``
This property is not supported.
*<themes>*
``<themes>``
Topics, as they are called in OpenLP, are fully supported, whereby only
the topic text (e. g. Grace) is considered, but neither the *id* nor
*lang*.
*<transposition>*
``<transposition>``
This property is not supported.
*<variant>*
``<variant>``
This property is not supported.
*<verse name="v1a" lang="he" translit="en">*
``<verse name="v1a" lang="he" translit="en">``
The attribute *translit* is not supported.
*<verseOrder>*
``<verseOrder>``
OpenLP supports this property.
"""
def __init__(self, manager):
self.manager = manager