Fixed up some of the docstrings and updated the documentation.

bzr-revno: 1284

documentation/api/source/openlp.rst

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

documentation/api/source/plugins/bibles.rst

@@ -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

openlp/core/ui/servicemanager.py

@@ -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,

openlp/plugins/bibles/lib/__init__.py

@@ -69,69 +69,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
+    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
     this::
 
         (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)
     match = get_reference_match(u'full').match(reference)
@@ -214,7 +235,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

openlp/plugins/songs/lib/songimport.py

@@ -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():

openlp/plugins/songs/lib/xml.py

@@ -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>*
+    ``<comments>``
-        The *<comments>* property is fully supported. But comments in lyrics
+        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