forked from openlp/openlp
Fix docstrings and update documentation.
This commit is contained in:
Raoul Snyman
parent
f80edf2092
commit
8abfd2ce14
@ -1,7 +0,0 @@
|
||||
.. _openlp:
|
||||
|
||||
:mod:`openlp` Module
|
||||
====================
|
||||
|
||||
.. automodule:: openlp
|
||||
:members:
|
||||
@ -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
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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)
|
||||
|
||||
``reference``
|
||||
The bible reference to parse.
|
||||
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:
|
||||
|
||||
``(?:(?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)
|
||||
@ -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
|
||||
|
||||
@ -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():
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user