From 32050a4c50e312d858b396b97159020eb0fa01cb Mon Sep 17 00:00:00 2001
From: Simon Conseil <contact@saimon.org>
Date: Fri, 30 May 2014 23:32:28 +0200
Subject: [PATCH] Add more docs and signals.

---
 docs/plugins.rst | 73 ++++++++++++++++++++++++++++++++++++++++++------
 sigal/gallery.py |  8 +++++-
 sigal/signals.py |  5 ++++
 3 files changed, 77 insertions(+), 9 deletions(-)

diff --git a/docs/plugins.rst b/docs/plugins.rst
index b9d781a..95b7c12 100644
--- a/docs/plugins.rst
+++ b/docs/plugins.rst
@@ -2,28 +2,85 @@
  Plugins
 =========
 
-Signals
--------
+How to use plugins
+------------------
 
-.. data:: sigal.signals.img_resized
-   :noindex:
+Plugins must be specified with the ``plugins`` setting:
 
-   Called after the image is resized.
+.. code-block:: python
+
+   from sigal.plugins import copyright
+   plugins = ['sigal.plugins.adjust', copyright]
+
+You can either specify the name of the module which contains the plugin, or
+import the plugin before adding it to the list. The ``plugin_paths`` setting
+can be used to specify paths to search for plugins (if they are not in the
+python path).
 
 Write a new plugin
 ------------------
 
-See an example with the copyright plugin:
+Plugins are based on signals with the blinker_ library. A plugin must
+subscribe to a signal (the list is given below). New signals can be added if
+need. See an example with the copyright plugin:
+
+.. _blinker: http://pythonhosted.org/blinker/
 
 .. literalinclude:: ../sigal/plugins/copyright.py
    :language: python
 
+Signals
+-------
+
+.. function:: sigal.signals.album_initialized(album)
+   :noindex:
+
+   Called after the :class:`~sigal.gallery.Album` is initialized.
+
+   :param album: the :class:`~sigal.gallery.Album` object.
+
+.. data:: sigal.signals.gallery_initialized(gallery)
+   :noindex:
+
+   Called after the gallery is initialized.
+
+   :param gallery: the :class:`Gallery` object.
+
+.. data:: sigal.signals.media_initialized(media)
+   :noindex:
+
+   Called after the :class:`~sigal.gallery.Media`
+   (:class:`~sigal.gallery.Image` or :class:`~sigal.gallery.Video`) is
+   initialized.
+
+   :param media: the media object.
+
+.. data:: sigal.signals.gallery_build(gallery)
+   :noindex:
+
+   Called after the gallery is build (after media are resized and html files
+   are written).
+
+   :param gallery: the :class:`Gallery` object.
+
+.. data:: sigal.signals.img_resized(img, settings=settings)
+   :noindex:
+
+   Called after the image is resized. This signal work differently, the
+   modified image object must be returned by the registered funtion.
+
+   :param img: the PIL image object.
+   :param settings: the settings dict.
+
+List of plugins
+---------------
+
 Adjust plugin
--------------
+=============
 
 .. automodule:: sigal.plugins.adjust
 
 Copyright plugin
-----------------
+================
 
 .. automodule:: sigal.plugins.copyright
diff --git a/sigal/gallery.py b/sigal/gallery.py
index a729642..6047a94 100644
--- a/sigal/gallery.py
+++ b/sigal/gallery.py
@@ -37,7 +37,7 @@ from datetime import datetime
 from os.path import isfile, join, splitext
 from PIL import Image as PILImage
 
-from . import image, video
+from . import image, video, signals
 from .compat import UnicodeMixin, strxfrm, url_quote
 from .image import process_image, get_exif_tags
 from .log import colored, BLUE
@@ -80,6 +80,7 @@ class Media(UnicodeMixin):
         self.raw_exif = None
         self.exif = None
         self.date = None
+        signals.media_initialized.send(self)
 
     def __repr__(self):
         return "<%s>(%r)" % (self.__class__.__name__, str(self))
@@ -221,6 +222,8 @@ class Album(UnicodeMixin):
 
             medias.sort(key=key, reverse=settings['medias_sort_reverse'])
 
+        signals.album_initialized.send(self)
+
     def __repr__(self):
         return "<%s>(path=%r, title=%r)" % (self.__class__.__name__, self.path,
                                             self.title)
@@ -458,6 +461,7 @@ class Gallery(object):
                 albums[relpath] = album
 
         self.logger.debug('Albums:\n%r', albums.values())
+        signals.gallery_initialized.send(self)
 
     def init_pool(self, ncpu):
         try:
@@ -527,6 +531,8 @@ class Gallery(object):
             for album in self.albums.values():
                 self.writer.write(album)
 
+        signals.gallery_build.send(self)
+
     def process_dir(self, album, force=False):
         """Process a list of images in a directory."""
 
diff --git a/sigal/signals.py b/sigal/signals.py
index b736128..c175d33 100644
--- a/sigal/signals.py
+++ b/sigal/signals.py
@@ -3,3 +3,8 @@
 from blinker import signal
 
 img_resized = signal('img_resized')
+
+album_initialized = signal('album_initialized')
+gallery_initialized = signal('gallery_initialized')
+gallery_build = signal('gallery_build')
+media_initialized = signal('media_initialized')