From 177d2d0351ddc781d0202022c5f05c95d2395836 Mon Sep 17 00:00:00 2001 From: Raoul Snyman Date: Mon, 11 Oct 2010 22:47:00 +0200 Subject: [PATCH] More documentation updates. --- documentation/source/plugins/bibles.rst | 23 ++++---- documentation/source/plugins/images.rst | 8 +++ documentation/source/plugins/index.rst | 21 +------ documentation/source/plugins/media.rst | 8 +++ .../source/plugins/presentations.rst | 40 +++++++++++++ documentation/source/plugins/songs.rst | 4 +- openlp/plugins/bibles/__init__.py | 2 +- openlp/plugins/bibles/lib/__init__.py | 38 ++++++++----- .../presentations/lib/powerpointcontroller.py | 56 ++++++++++--------- .../lib/presentationcontroller.py | 31 +++++----- 10 files changed, 146 insertions(+), 85 deletions(-) create mode 100644 documentation/source/plugins/images.rst create mode 100644 documentation/source/plugins/media.rst create mode 100644 documentation/source/plugins/presentations.rst diff --git a/documentation/source/plugins/bibles.rst b/documentation/source/plugins/bibles.rst index c042feb56..5f2c688d5 100644 --- a/documentation/source/plugins/bibles.rst +++ b/documentation/source/plugins/bibles.rst @@ -1,7 +1,7 @@ .. _plugins-bibles: -:mod:`bibles` Plugin -==================== +Bibles Plugin +============= .. automodule:: openlp.plugins.bibles :members: @@ -60,8 +60,8 @@ .. autoclass:: openlp.plugins.bibles.lib.http.HTTPBible :members: -:mod:`bibleOSISimpl` -^^^^^^^^^^^^^^^^^^^^ +:mod:`osis` +^^^^^^^^^^^ .. automodule:: openlp.plugins.bibles.lib.osis :members: @@ -69,18 +69,21 @@ .. autoclass:: openlp.plugins.bibles.lib.osis.OSISBible :members: +:mod:`opensong` +^^^^^^^^^^^^^^^ + +.. automodule:: openlp.plugins.bibles.lib.opensong + :members: + +.. autoclass:: openlp.plugins.bibles.lib.opensong.OpenSongBible + :members: + :mod:`biblestab` ^^^^^^^^^^^^^^^^ .. automodule:: openlp.plugins.bibles.lib.biblestab :members: -:mod:`common` -^^^^^^^^^^^^^ - -.. automodule:: openlp.plugins.bibles.lib.common - :members: - :mod:`manager` ^^^^^^^^^^^^^^ diff --git a/documentation/source/plugins/images.rst b/documentation/source/plugins/images.rst new file mode 100644 index 000000000..d4d6fa265 --- /dev/null +++ b/documentation/source/plugins/images.rst @@ -0,0 +1,8 @@ +.. _plugins-images: + +Images Plugin +============= + +.. automodule:: openlp.plugins.images + :members: + diff --git a/documentation/source/plugins/index.rst b/documentation/source/plugins/index.rst index 713005c3d..6c5b139d5 100644 --- a/documentation/source/plugins/index.rst +++ b/documentation/source/plugins/index.rst @@ -11,24 +11,9 @@ songs bibles - -:mod:`presentations` Plugin ---------------------------- - -.. automodule:: openlp.plugins.presentations - :members: - -:mod:`media` Plugin -------------------- - -.. automodule:: openlp.plugins.media - :members: - -:mod:`images` Plugin --------------------- - -.. automodule:: openlp.plugins.images - :members: + presentations + media + images :mod:`custom` Plugin -------------------- diff --git a/documentation/source/plugins/media.rst b/documentation/source/plugins/media.rst new file mode 100644 index 000000000..637fec634 --- /dev/null +++ b/documentation/source/plugins/media.rst @@ -0,0 +1,8 @@ +.. _plugins-media: + +Media Plugin +============ + +.. automodule:: openlp.plugins.media + :members: + diff --git a/documentation/source/plugins/presentations.rst b/documentation/source/plugins/presentations.rst new file mode 100644 index 000000000..dd688ddf6 --- /dev/null +++ b/documentation/source/plugins/presentations.rst @@ -0,0 +1,40 @@ +.. _plugins-presentations: + +Presentations Plugin +==================== + +Plugin Class +------------ + +.. autoclass:: openlp.plugins.presentations.presentationplugin.PresentationPlugin + :members: + +Helper Classes & Functions +-------------------------- + +.. automodule:: openlp.plugins.presentations.lib + :members: + +.. automodule:: openlp.plugins.presentations.lib.mediaitem + :members: + +.. automodule:: openlp.plugins.presentations.lib.presentationtab + :members: + +.. automodule:: openlp.plugins.presentations.lib.messagelistener + :members: + +.. automodule:: openlp.plugins.presentations.lib.presentationcontroller + :members: + +Presentation Application Controllers +------------------------------------ + +.. automodule:: openlp.plugins.presentations.lib.impresscontroller + :members: + +.. automodule:: openlp.plugins.presentations.lib.pptviewcontroller + :members: + +.. automodule:: openlp.plugins.presentations.lib.powerpointcontroller + :members: diff --git a/documentation/source/plugins/songs.rst b/documentation/source/plugins/songs.rst index 2ce744ddd..5378ba7d7 100644 --- a/documentation/source/plugins/songs.rst +++ b/documentation/source/plugins/songs.rst @@ -1,7 +1,7 @@ .. _plugins-songs: -:mod:`songs` Plugin -=================== +Songs Plugin +============ .. automodule:: openlp.plugins.songs :members: diff --git a/openlp/plugins/bibles/__init__.py b/openlp/plugins/bibles/__init__.py index 0a158d1a7..a1e8f5a51 100644 --- a/openlp/plugins/bibles/__init__.py +++ b/openlp/plugins/bibles/__init__.py @@ -24,6 +24,6 @@ # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### """ -The :mod:`bibles' module provides the Bible plugin to enable OpenLP to display +The :mod:`bibles` module provides the Bible plugin to enable OpenLP to display scripture. """ diff --git a/openlp/plugins/bibles/lib/__init__.py b/openlp/plugins/bibles/lib/__init__.py index 06f9d7cc7..a6fc03045 100644 --- a/openlp/plugins/bibles/lib/__init__.py +++ b/openlp/plugins/bibles/lib/__init__.py @@ -60,22 +60,32 @@ def parse_reference(reference): and converts it to a reference list, a list of references to be queried from the Bible database files. - BIBLE_REFERENCE regular expression produces the following match groups: - 0 This is a special group consisting of the whole string that matched. - 1 [\w ]+ The book the reference is from. - 2 [0-9]+ The first (or only) chapter in the reference. - 3 None|[0-9]+ None or the only verse or the first verse in a - verse range or the start verse in a chapter range. - 4 None|[0-9]+|end None or the end verse of the first verse range or - the end chapter of a chapter range. - 5 None|[0-9]+ None or the second chapter in multiple - (non-ranged) chapters. - 6 None|[0-9]+|end None, the start of the second verse range or the - end of a chapter range. - 7 None|[0-9]+|end None or the end of the second verse range. + The ``BIBLE_REFERENCE`` constant regular expression produces the following + match groups: + + 0. (match string) + This is a special group consisting of the whole string that matched. + 1. ``[\w ]+`` + The book the reference is from. + 2. ``[0-9]+`` + The first (or only) chapter in the reference. + 3. ``None`` or ``[0-9]+`` + ``None``, or the only verse, or the first verse in a verse range or, + the start verse in a chapter range. + 4. ``None`` or ``[0-9]+`` or ``end`` + ``None``, or the end verse of the first verse range, or the end chapter + of a chapter range. + 5. ``None`` or ``[0-9]+`` + ``None``, or the second chapter in multiple (non-ranged) chapters. + 6. ``None`` or ``[0-9]+`` or ``end`` + ``None``, the start of the second verse range. or the end of a chapter + range. + 7. ``None`` or ``[0-9]+`` or ``end`` + ``None``, or the end of the second verse range. The reference list is a list of tuples, with each tuple structured like this:: + (book, chapter, start_verse, end_verse) ``reference`` @@ -154,7 +164,7 @@ def parse_reference(reference): class SearchResults(object): """ - Encapsulate a set of search results. This is Bible-type independant. + Encapsulate a set of search results. This is Bible-type independent. """ def __init__(self, book, chapter, verselist): """ diff --git a/openlp/plugins/presentations/lib/powerpointcontroller.py b/openlp/plugins/presentations/lib/powerpointcontroller.py index 5059f5f76..58bb6b3d6 100644 --- a/openlp/plugins/presentations/lib/powerpointcontroller.py +++ b/openlp/plugins/presentations/lib/powerpointcontroller.py @@ -110,10 +110,10 @@ class PowerpointDocument(PresentationDocument): """ Class which holds information and controls a single presentation """ - + def __init__(self, controller, presentation): """ - Constructor, store information about the file and initialise + Constructor, store information about the file and initialise """ log.debug(u'Init Presentation Powerpoint') PresentationDocument.__init__(self, controller, presentation) @@ -125,13 +125,13 @@ class PowerpointDocument(PresentationDocument): Opens the PowerPoint file using the process created earlier ``presentation`` - The file name of the presentations to run. + The file name of the presentations to run. """ log.debug(u'LoadPresentation') if not self.controller.process or not self.controller.process.Visible: self.controller.start_process() try: - self.controller.process.Presentations.Open(self.filepath, False, + self.controller.process.Presentations.Open(self.filepath, False, False, True) except pywintypes.com_error: return False @@ -143,22 +143,24 @@ class PowerpointDocument(PresentationDocument): def create_thumbnails(self): """ Create the thumbnail images for the current presentation. - Note an alternative and quicker method would be do + + Note an alternative and quicker method would be do:: + self.presentation.Slides[n].Copy() thumbnail = QApplication.clipboard.image() - But for now we want a physical file since it makes - life easier elsewhere + + However, for the moment, we want a physical file since it makes life + easier elsewhere. """ if self.check_thumbnails(): return - self.presentation.Export(os.path.join(self.get_thumbnail_folder(), ''), + self.presentation.Export(os.path.join(self.get_thumbnail_folder(), ''), 'png', 320, 240) def close_presentation(self): """ - Close presentation and clean up objects - Triggerent by new object being added to SlideController orOpenLP - being shut down + Close presentation and clean up objects. This is triggered by a new + object being added to SlideController or OpenLP being shut down. """ log.debug(u'ClosePresentation') if self.presentation: @@ -171,7 +173,7 @@ class PowerpointDocument(PresentationDocument): def is_loaded(self): """ - Returns true if a presentation is loaded + Returns ``True`` if a presentation is loaded. """ try: if not self.controller.process.Visible: @@ -187,7 +189,7 @@ class PowerpointDocument(PresentationDocument): def is_active(self): """ - Returns true if a presentation is currently active + Returns ``True`` if a presentation is currently active. """ if not self.is_loaded(): return False @@ -202,7 +204,7 @@ class PowerpointDocument(PresentationDocument): def unblank_screen(self): """ - Unblanks (restores) the presentationn + Unblanks (restores) the presentation. """ self.presentation.SlideShowSettings.Run() self.presentation.SlideShowWindow.View.State = 1 @@ -210,13 +212,13 @@ class PowerpointDocument(PresentationDocument): def blank_screen(self): """ - Blanks the screen + Blanks the screen. """ self.presentation.SlideShowWindow.View.State = 3 def is_blank(self): """ - Returns true if screen is blank + Returns ``True`` if screen is blank. """ if self.is_active(): return self.presentation.SlideShowWindow.View.State == 3 @@ -225,14 +227,14 @@ class PowerpointDocument(PresentationDocument): def stop_presentation(self): """ - Stops the current presentation and hides the output + Stops the current presentation and hides the output. """ self.presentation.SlideShowWindow.View.Exit() if os.name == u'nt': def start_presentation(self): """ - Starts a presentation from the beginning + Starts a presentation from the beginning. """ #SlideShowWindow measures its size/position by points, not pixels try: @@ -254,40 +256,40 @@ class PowerpointDocument(PresentationDocument): def get_slide_number(self): """ - Returns the current slide number + Returns the current slide number. """ return self.presentation.SlideShowWindow.View.CurrentShowPosition def get_slide_count(self): """ - Returns total number of slides + Returns total number of slides. """ return self.presentation.Slides.Count def goto_slide(self, slideno): """ - Moves to a specific slide in the presentation + Moves to a specific slide in the presentation. """ self.presentation.SlideShowWindow.View.GotoSlide(slideno) def next_step(self): """ - Triggers the next effect of slide on the running presentation + Triggers the next effect of slide on the running presentation. """ self.presentation.SlideShowWindow.View.Next() def previous_step(self): """ - Triggers the previous slide on the running presentation + Triggers the previous slide on the running presentation. """ self.presentation.SlideShowWindow.View.Previous() def get_slide_text(self, slide_no): """ - Returns the text on the slide + Returns the text on the slide. ``slide_no`` - The slide the text is required for, starting at 1 + The slide the text is required for, starting at 1. """ text = '' shapes = self.presentation.Slides(slide_no).Shapes @@ -299,10 +301,10 @@ class PowerpointDocument(PresentationDocument): def get_slide_notes(self, slide_no): """ - Returns the text on the slide + Returns the text on the slide. ``slide_no`` - The slide the notes are required for, starting at 1 + The slide the notes are required for, starting at 1. """ text = '' shapes = self.presentation.Slides(slide_no).NotesPage.Shapes diff --git a/openlp/plugins/presentations/lib/presentationcontroller.py b/openlp/plugins/presentations/lib/presentationcontroller.py index 15f84dc5e..5bd0719e9 100644 --- a/openlp/plugins/presentations/lib/presentationcontroller.py +++ b/openlp/plugins/presentations/lib/presentationcontroller.py @@ -37,16 +37,21 @@ log = logging.getLogger(__name__) class PresentationController(object): """ - Base class for presentation controllers to inherit from - Class to control interactions with presentations. - It creates the runtime environment - To create a new controller, take a copy of this file and name it - so it ends in controller.py, i.e. foobarcontroller.py - Make sure it inherits PresentationController - Then fill in the blanks. If possible try and make sure it loads - on all platforms, using for example os.name checks, although - __init__, check_available and presentation_deleted should always work. - See impresscontroller, powerpointcontroller or pptviewcontroller + This class is used to control interactions with presentation applications + by creating a runtime environment. This is a base class for presentation + controllers to inherit from. + + To create a new controller, take a copy of this file and name it so it ends + with ``controller.py``, i.e. ``foobarcontroller.py``. Make sure it inherits + :class:`~openlp.plugins.presentations.lib.presentationcontroller.PresentationController`, + and then fill in the blanks. If possible try to make sure it loads on all + platforms, usually by using :mod:``os.name`` checks, although + ``__init__``, ``check_available`` and ``presentation_deleted`` should + always be implemented. + + See :class:`~openlp.plugins.presentations.lib.impresscontroller.ImpressController`, + :class:`~openlp.plugins.presentations.lib.powerpointcontroller.PowerpointController` or + :class:`~openlp.plugins.presentations.lib.pptviewcontroller.PptviewController` for examples. **Basic Attributes** @@ -70,7 +75,7 @@ class PresentationController(object): ``alsosupports`` Other file types the application can import, although not necessarily the first choice due to potential incompatibilities - + **Hook Functions** ``kill()`` @@ -246,7 +251,7 @@ class PresentationDocument(object): ``presentation`` The file name of the presentations to the run. - + Returns False if the file could not be opened """ return False @@ -387,7 +392,7 @@ class PresentationDocument(object): if os.path.isfile(file): img = resize_image(file, 320, 240) img.save(self.get_thumbnail_path(idx, False)) - + def get_thumbnail_path(self, slide_no, check_exists): """ Returns an image path containing a preview for the requested slide