Update 'extending' documentation

TODO.txt

@@ -1,27 +1,23 @@
+
 Bugs
 ====
 
 General
 =======
-- Checks for the existence of external programs
-- More logging (debug/info)
-- Replace non-interactive puts()-calls with logging.info()-calls
 - Add support for different scanning profiles that can be selected
   (e.g.: 'illustrations', 'text')
-- Add support for (optional) configuration file
-- Allow more ScanTailor fine-tuning
+- More tests, espescially for included plugins
 
 API
 ===
-- Hooks for plugins in commands.postprocess and commands.wizard
-- Better docstrings (at least for public interfaces)
+- Hooks for plugins in commands.wizard
 - Refactor to abstract as much away from UI-specific code to prepare for an
   eventual (optional) PySide GUI.
 
 Plugin ideas
 ============
 - OCR plugin leveraging ocropus or tesseract
-- CBR (rar), PDF (pdfbeads) and DJVU (djvubind) plugins for postprocess
-- Metadata plugin for postprocess using OpenLibrary for ISBN-queries and
-  Dublin Core for serialization
+- CBR (rar) plugin
+- Metadata plugin using OpenLibrary for ISBN-queries and Dublin Core for
+  serialization
 - Archive.org upload plugin

doc/extending.rst

@@ -14,5 +14,59 @@ implementation based on their USB device and vendor IDs. This means that you
 can support a whole range of devices with a single :class:`CameraPlugin
 <spreads.plugin.CameraPlugin>` implementation, if you know their respective IDs.
 
-.. seealso:: module :py:mod:`spreads.util`
 .. _plugin for the Canon A2200: https://github.com/jbaiter/spreads/blob/master/spreadsplug/a2200.py
+
+.. _extend_commands:
+
+Extending *spreads* functionality
+=================================
+You can extend all of *spread's* built-in commands with your own code. To do,
+you just have to inherit from one of the :class:`SpreadsPlugin
+<spreads.plugin.SpreadsPlugin>` subclasses and implement one or more of their
+abstract methods.  The following types of plugins are available:
+
+ShootPlugin
+-----------
+See :class:`ShootPlugin <spreads.plugin.ShootPlugin>`.
+
+You can hook into the **shoot** command by implementing :meth:`snap` (executed
+every time both cameras have captured an image) and :meth:`finish` (executed
+once the shooting workflow has finished).
+
+DownloadPlugin
+--------------
+See :class:`DownloadPlugin <spreads.plugin.DownloadPlugin>`.
+
+Do stuff with the images downloaded from the camera by implementing
+:meth:`download <spreads.plugins.DownloadPlugin.download>` (executed once all
+files are downloaded) and :meth:`delete <spreads.plugin.DownloadPlugin.delete>`
+(executed once all files are deleted). By convention, all
+:class:`DownloadPlugin <spreads.plugin.DownloadPlugin>` implementations only
+modify the downloaded images in a **lossless** way, this means that while
+information may be added to them (e.g. setting new metadata fields, rotating
+them while preserving image quality, etc), no lossy changes may occur. Use
+:class:`FilterPlugin <spreads.plugin.FilterPlugin>` for these types of changes.
+
+Example implementation: spreadsplug.combine_
+
+.. _spreadsplug.combine: https://github.com/jbaiter/spreads/blob/master/spreadsplug/combine.py
+
+
+FilterPlugin
+------------
+See :class:`FilterPlugin <spreads.plugin.FilterPlugin>`.
+
+Most plugins will probably fall into this category. Implement the :meth:`process
+<spreads.plugin.FilterPlugin.process>` method to deal with the downloaded
+images in ``project-path/raw`` in any way you please, as long as you don't
+overwrite them.
+
+Example implementations:
+
+- spreadsplug.scantailor_ (image postprocessing)
+- spreadsplug.pdfbeans_ (output generation)
+
+.. _spreadsplug.scantailor: https://github.com/jbaiter/spreads/blob/master/spreadsplug/scantailor.py
+.. _spreadsplug.pdfbeans: https://github.com/jbaiter/spreads/blob/master/spreadsplug/pdfbeans.py
+
+.. seealso:: module :py:mod:`spreads.plugin`, module :py:mod:`spreads.util`

doc/index.rst

@@ -17,9 +17,9 @@ by supplying arguments beforehand, or by inspecting the output and
 applying your modifications.
 
 *spreads* is meant to be fully customizable. This means, :ref:`adding support
-for new cameras <add_cameras>` is made as painless as possible.  Support for
-plugins that can either hook into the various commands or add new ones is on
-the agenda, stay tuned!
+for new cameras <add_cameras>` is made as painless as possible. You can also
+hook into any of the *spread* commands by imlementing one of the available
+:ref:`plugin classes <extend_commands>`
 
 
 Quickstart