openlp-core team mailing list archive
-
openlp-core team
-
Mailing list archive
-
Message #06133
[Merge] lp:~raoul-snyman/openlp/api-documentation into lp:openlp
Raoul Snyman has proposed merging lp:~raoul-snyman/openlp/api-documentation into lp:openlp.
Requested reviews:
OpenLP Core (openlp-core)
For more details, see:
https://code.launchpad.net/~raoul-snyman/openlp/api-documentation/+merge/49183
Fixed up some of the docstrings and updated the documentation.
--
https://code.launchpad.net/~raoul-snyman/openlp/api-documentation/+merge/49183
Your team OpenLP Core is requested to review the proposed merge of lp:~raoul-snyman/openlp/api-documentation into lp:openlp.
=== removed file 'documentation/api/source/openlp.rst'
--- documentation/api/source/openlp.rst 2010-09-14 18:18:47 +0000
+++ documentation/api/source/openlp.rst 1970-01-01 00:00:00 +0000
@@ -1,7 +0,0 @@
-.. _openlp:
-
-:mod:`openlp` Module
-====================
-
-.. automodule:: openlp
- :members:
=== modified file 'documentation/api/source/plugins/bibles.rst'
--- documentation/api/source/plugins/bibles.rst 2010-10-16 19:38:23 +0000
+++ documentation/api/source/plugins/bibles.rst 2011-02-10 05:34:05 +0000
@@ -18,7 +18,7 @@
.. automodule:: openlp.plugins.bibles.forms
:members:
-.. autoclass:: openlp.plugins.bibles.forms.importwizardform.ImportWizardForm
+.. autoclass:: openlp.plugins.bibles.forms.bibleimportform.BibleImportForm
:members:
Helper Classes & Functions
=== modified file 'openlp/core/ui/servicemanager.py'
--- openlp/core/ui/servicemanager.py 2011-02-06 20:26:32 +0000
+++ openlp/core/ui/servicemanager.py 2011-02-10 05:34:05 +0000
@@ -461,7 +461,7 @@
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,
=== modified file 'openlp/plugins/bibles/lib/__init__.py'
--- openlp/plugins/bibles/lib/__init__.py 2011-02-07 16:29:06 +0000
+++ openlp/plugins/bibles/lib/__init__.py 2011-02-10 05:34:05 +0000
@@ -69,69 +69,90 @@
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.
-
- This is a user manual like description, how the references are working.
-
- - 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.
+ typed in string and converts it to a list of references to be queried from
+ the Bible database files.
+
+ ``reference``
+ A string. The Bible reference to parse.
+
+ 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 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:
- 1. ``(?:(?P<from_chapter>[0-9]+)%(sep_v)s)?``
+ ``(?:(?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]+)``
+
+ ``(?P<from_verse>[0-9]+)``
The verse reference ``from_verse`` is manditory
- 3. ``(?P<range_to>%(sep_r)s(?:`` ... ``|%(sep_e)s)?)?``
+
+ ``(?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)?``
+
+ ``(?:(?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]+)``
+
+ ``(?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*``
+ ``^\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*$``
+
+ ``(?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.
- The reference list is a list of tuples, with each tuple structured like
- this::
-
- (book, chapter, from_verse, to_verse)
-
- ``reference``
- The bible reference to parse.
-
- Returns None or a reference list.
"""
log.debug(u'parse_reference("%s")', reference)
match = get_reference_match(u'full').match(reference)
@@ -201,7 +222,7 @@
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):
"""
@@ -214,7 +235,8 @@
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
=== modified file 'openlp/plugins/songs/lib/songimport.py'
--- openlp/plugins/songs/lib/songimport.py 2011-01-26 23:26:09 +0000
+++ openlp/plugins/songs/lib/songimport.py 2011-02-10 05:34:05 +0000
@@ -50,6 +50,7 @@
``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 @@
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 @@
``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():
=== modified file 'openlp/plugins/songs/lib/xml.py'
--- openlp/plugins/songs/lib/xml.py 2011-01-20 05:42:27 +0000
+++ openlp/plugins/songs/lib/xml.py 2011-02-10 05:34:05 +0000
@@ -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 @@
</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 @@
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 @@
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>*
- This property is not supported.
-
- *<key>*
- This property is not supported.
-
- *<keywords>*
- This property is not supported.
-
- *<lines>*
+ ``<customVersion>``
+ This property is not supported.
+
+ ``<key>``
+ This property is not supported.
+
+ ``<keywords>``
+ This property is not supported.
+
+ ``<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>*
- This property is not supported.
-
- *<variant>*
- This property is not supported.
-
- *<verse name="v1a" lang="he" translit="en">*
+ ``<transposition>``
+ This property is not supported.
+
+ ``<variant>``
+ This property is not supported.
+
+ ``<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
Follow ups
