forked from openlp/openlp
Fix docstrings and update documentation.
This commit is contained in:
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
|
.. automodule:: openlp.plugins.bibles.forms
|
||||||
:members:
|
:members:
|
||||||
|
|
||||||
.. autoclass:: openlp.plugins.bibles.forms.importwizardform.ImportWizardForm
|
.. autoclass:: openlp.plugins.bibles.forms.bibleimportform.BibleImportForm
|
||||||
:members:
|
:members:
|
||||||
|
|
||||||
Helper Classes & Functions
|
Helper Classes & Functions
|
||||||
|
@ -461,7 +461,7 @@ class ServiceManager(QtGui.QWidget):
|
|||||||
|
|
||||||
def saveFileAs(self):
|
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.
|
save the file.
|
||||||
"""
|
"""
|
||||||
fileName = unicode(QtGui.QFileDialog.getSaveFileName(self.mainwindow,
|
fileName = unicode(QtGui.QFileDialog.getSaveFileName(self.mainwindow,
|
||||||
|
@ -62,69 +62,90 @@ def get_reference_match(match_type):
|
|||||||
def parse_reference(reference):
|
def parse_reference(reference):
|
||||||
"""
|
"""
|
||||||
This is the next generation über-awesome function that takes a person's
|
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
|
typed in string and converts it to a list of references to be queried from
|
||||||
be queried from the Bible database files.
|
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.
|
Returns ``None`` or a reference list.
|
||||||
``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.
|
|
||||||
|
|
||||||
The reference list is a list of tuples, with each tuple structured like
|
The reference list is a list of tuples, with each tuple structured like
|
||||||
this::
|
this::
|
||||||
|
|
||||||
(book, chapter, from_verse, to_verse)
|
(book, chapter, from_verse, to_verse)
|
||||||
|
|
||||||
``reference``
|
For example::
|
||||||
The bible reference to parse.
|
|
||||||
|
[(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)
|
log.debug(u'parse_reference("%s")', reference)
|
||||||
match = get_reference_match(u'full').match(reference)
|
match = get_reference_match(u'full').match(reference)
|
||||||
@ -207,7 +228,8 @@ class SearchResults(object):
|
|||||||
The chapter of the book.
|
The chapter of the book.
|
||||||
|
|
||||||
``verselist``
|
``verselist``
|
||||||
The list of verses for this reading
|
The list of verses for this reading.
|
||||||
|
|
||||||
"""
|
"""
|
||||||
self.book = book
|
self.book = book
|
||||||
self.chapter = chapter
|
self.chapter = chapter
|
||||||
|
@ -50,6 +50,7 @@ class SongImport(QtCore.QObject):
|
|||||||
``manager``
|
``manager``
|
||||||
An instance of a SongManager, through which all database access is
|
An instance of a SongManager, through which all database access is
|
||||||
performed.
|
performed.
|
||||||
|
|
||||||
"""
|
"""
|
||||||
self.manager = manager
|
self.manager = manager
|
||||||
self.stop_import_flag = False
|
self.stop_import_flag = False
|
||||||
@ -199,7 +200,7 @@ class SongImport(QtCore.QObject):
|
|||||||
|
|
||||||
def add_verse(self, versetext, versetag=u'V', lang=None):
|
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
|
attempt to detect duplicates. In this case it will just add to the verse
|
||||||
order.
|
order.
|
||||||
|
|
||||||
@ -212,6 +213,7 @@ class SongImport(QtCore.QObject):
|
|||||||
|
|
||||||
``lang``
|
``lang``
|
||||||
The language code (ISO-639) of the verse, for example *en* or *de*.
|
The language code (ISO-639) of the verse, for example *en* or *de*.
|
||||||
|
|
||||||
"""
|
"""
|
||||||
for (oldversetag, oldverse, oldlang) in self.verses:
|
for (oldversetag, oldverse, oldlang) in self.verses:
|
||||||
if oldverse.strip() == versetext.strip():
|
if oldverse.strip() == versetext.strip():
|
||||||
|
@ -26,7 +26,7 @@
|
|||||||
"""
|
"""
|
||||||
The :mod:`xml` module provides the XML functionality.
|
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"?>
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
<song version="1.0">
|
<song version="1.0">
|
||||||
@ -38,7 +38,7 @@ The basic XML for storing the lyrics in the song database is of the format::
|
|||||||
</song>
|
</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"
|
<song xmlns="http://openlyrics.info/namespace/2009/song"
|
||||||
version="0.7"
|
version="0.7"
|
||||||
@ -86,7 +86,7 @@ class SongXML(object):
|
|||||||
|
|
||||||
def add_verse_to_lyrics(self, type, number, content, lang=None):
|
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``
|
``type``
|
||||||
A string denoting the type of verse. Possible values are "V",
|
A string denoting the type of verse. Possible values are "V",
|
||||||
@ -158,59 +158,60 @@ class OpenLyrics(object):
|
|||||||
to/from a song.
|
to/from a song.
|
||||||
|
|
||||||
As OpenLyrics has a rich set of different features, we cannot support them
|
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*.
|
OpenLP does not support the attribute *type* and *lang*.
|
||||||
|
|
||||||
*<chord>*
|
``<chord>``
|
||||||
This property is not supported.
|
This property is not supported.
|
||||||
|
|
||||||
*<comments>*
|
``<comments>``
|
||||||
The *<comments>* property is fully supported. But comments in lyrics
|
The ``<comments>`` property is fully supported. But comments in lyrics
|
||||||
are not supported.
|
are not supported.
|
||||||
|
|
||||||
*<copyright>*
|
``<copyright>``
|
||||||
This property is fully supported.
|
This property is fully supported.
|
||||||
|
|
||||||
*<customVersion>*
|
``<customVersion>``
|
||||||
This property is not supported.
|
This property is not supported.
|
||||||
|
|
||||||
*<key>*
|
``<key>``
|
||||||
This property is not supported.
|
This property is not supported.
|
||||||
|
|
||||||
*<keywords>*
|
``<keywords>``
|
||||||
This property is not supported.
|
This property is not supported.
|
||||||
|
|
||||||
*<lines>*
|
``<lines>``
|
||||||
The attribute *part* is not supported.
|
The attribute *part* is not supported.
|
||||||
|
|
||||||
*<publisher>*
|
``<publisher>``
|
||||||
This property is not supported.
|
This property is not supported.
|
||||||
|
|
||||||
*<songbooks>*
|
``<songbooks>``
|
||||||
As OpenLP does only support one songbook, we cannot consider more than
|
As OpenLP does only support one songbook, we cannot consider more than
|
||||||
one songbook.
|
one songbook.
|
||||||
|
|
||||||
*<tempo>*
|
``<tempo>``
|
||||||
This property is not supported.
|
This property is not supported.
|
||||||
|
|
||||||
*<themes>*
|
``<themes>``
|
||||||
Topics, as they are called in OpenLP, are fully supported, whereby only
|
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
|
the topic text (e. g. Grace) is considered, but neither the *id* nor
|
||||||
*lang*.
|
*lang*.
|
||||||
|
|
||||||
*<transposition>*
|
``<transposition>``
|
||||||
This property is not supported.
|
This property is not supported.
|
||||||
|
|
||||||
*<variant>*
|
``<variant>``
|
||||||
This property is not supported.
|
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.
|
The attribute *translit* is not supported.
|
||||||
|
|
||||||
*<verseOrder>*
|
``<verseOrder>``
|
||||||
OpenLP supports this property.
|
OpenLP supports this property.
|
||||||
|
|
||||||
"""
|
"""
|
||||||
def __init__(self, manager):
|
def __init__(self, manager):
|
||||||
self.manager = manager
|
self.manager = manager
|
||||||
|
Loading…
Reference in New Issue
Block a user