From ce719afeed5a0cbc33d0cb4e04a9764ed2633a27 Mon Sep 17 00:00:00 2001
From: Stefan van der Walt <stefan@sun.ac.za>
Date: Sun, 8 Nov 2009 01:21:34 +0200
Subject: [PATCH] Add user guide and documentation on plugins.

---
 doc/source/user_guide.txt         |  8 +++
 doc/source/user_guide/plugins.txt | 84 +++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 doc/source/user_guide.txt
 create mode 100644 doc/source/user_guide/plugins.txt

diff --git a/doc/source/user_guide.txt b/doc/source/user_guide.txt
new file mode 100644
index 00000000..f011c8df
--- /dev/null
+++ b/doc/source/user_guide.txt
@@ -0,0 +1,8 @@
+User Guide
+==========
+
+.. contents::
+   :local:
+
+.. include:: user_guide/plugins.txt
+
diff --git a/doc/source/user_guide/plugins.txt b/doc/source/user_guide/plugins.txt
new file mode 100644
index 00000000..c68c5a23
--- /dev/null
+++ b/doc/source/user_guide/plugins.txt
@@ -0,0 +1,84 @@
+I/O Plugin Infrastructure
+-------------------------
+A plugin consists of two files, the source and the descriptor ``.ini``.  Let's
+say we'd like to provide a plugin for ``imshow`` using ``matplotlib``.  We'll
+call our plugin ``mpl``::
+
+  scikits/image/io/_plugins/mpl.py
+  scikits/image/io/_plugins/mpl.ini
+
+The name of the ``.py`` and ``.ini`` files must correspond.  Inside the
+``.ini`` file, we give the plugin meta-data::
+
+  [mpl] <-- name of the plugin, may be anything
+  description = Matplotlib image I/O plugin
+  provides = imshow <-- a comma-separated list, one or more of
+                        imshow, imsave, imread, _app_show
+
+The "provides"-line lists all the functions provided by the plugin.  Since our
+plugin provides ``imshow``, we have to define it inside ``mpl.py``::
+
+  # This is mpl.py
+
+  import matplotlib.pyplot as plt
+
+  def imshow(img):
+      plt.imshow(img)
+
+Note that, by default, ``imshow`` is non-blocking, so a special function
+``_app_show`` must be provided to block the GUI.  We can modify our plugin to
+provide it as follows::
+
+  [mpl]
+  provides = imshow, _app_show
+
+::
+
+  # This is mpl.py
+
+  import matplotlib.pyplot as plt
+
+  def imshow(img):
+      plt.imshow(img)
+
+  def _app_show():
+      plt.show()
+
+Any plugin in the ``_plugins`` directory is automatically examined by
+``scikits.image.io`` upon import.  You may list all the plugins on your
+system::
+
+  >>> import scikits.image.io as io
+  >>> io.plugins()
+  {'gtk': ['imshow'],
+   'matplotlib': ['imshow', 'imsave'],
+   'pil': ['imread'],
+   'qt': ['imshow'],
+   'test': ['imsave', 'imshow', 'imread']}
+
+or only those already loaded::
+
+  >>> io.plugins(loaded=True)
+  {'pil': ['imread']}
+
+A plugin is loaded using the ``use_plugin`` command::
+
+  >>> import scikits.image.io as io
+  >>> io.use_plugin('pil') # Use all capabilities provided by PIL
+
+or
+
+::
+
+  >>> io.use_plugin('pil', 'imread') # Use only the imread capability of PIL
+
+Note that, if more than one plugin provides certain functionality, the
+last plugin loaded is used.
+
+To query a plugin's capabilities, use ``plugin_info``::
+
+  >>> io.plugin_info('pil')
+  >>> 
+  {'description': 'Image reading via the Python Imaging Library',
+   'provides': 'imread'}
+