From 52ff2b947dc26b906af4d8a547efa0ad1618d8a9 Mon Sep 17 00:00:00 2001
From: Simon Conseil <contact@saimon.org>
Date: Thu, 4 Sep 2014 22:49:01 +0200
Subject: [PATCH] Add warnings about imports in the settings file, to avoid
 breaking the multiprocessing feature.

---
 docs/plugins.rst              | 17 +++++++++++++----
 sigal/templates/sigal.conf.py |  6 ++++++
 tests/sample/sigal.conf.py    |  3 +--
 3 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/docs/plugins.rst b/docs/plugins.rst
index 95b7c12..06d6b2b 100644
--- a/docs/plugins.rst
+++ b/docs/plugins.rst
@@ -7,15 +7,24 @@ How to use plugins
 
 Plugins must be specified with the ``plugins`` setting:
 
+.. code-block:: python
+
+   plugins = ['sigal.plugins.adjust', 'sigal.plugins.copyright']
+
+You can either specify the name of the module which contains the plugin, or
+import the plugin before adding it to the list:
+
 .. 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).
+.. note:: Using an import like this will break the multiprocessing feature,
+    because the settings dict must be serializable. So in most cases you should
+    prefer the first option.
+
+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
 ------------------
diff --git a/sigal/templates/sigal.conf.py b/sigal/templates/sigal.conf.py
index 26dd48c..0d27dff 100644
--- a/sigal/templates/sigal.conf.py
+++ b/sigal/templates/sigal.conf.py
@@ -138,6 +138,12 @@ ignore_files = []
 # Plugins
 # --------
 
+# List of plugins to use. The values must be a path than can be imported.
+# Another option is to import the plugin and put the module in the list, but
+# this will break with the multiprocessing feature (the settings dict obtained
+# from this file must be serializable).
+# plugins = ['sigal.plugins.adjust', 'sigal.plugins.copyright']
+
 # Add a copyright text on the image (default: '')
 # copyright = "© An example copyright message"
 
diff --git a/tests/sample/sigal.conf.py b/tests/sample/sigal.conf.py
index ec6a44a..e693f83 100644
--- a/tests/sample/sigal.conf.py
+++ b/tests/sample/sigal.conf.py
@@ -8,8 +8,7 @@ keep_orig = True
 links = [('Example link', 'http://example.org'),
          ('Another link', 'http://example.org')]
 
-from sigal.plugins import copyright
-plugins = ['sigal.plugins.adjust', copyright]
+plugins = ['sigal.plugins.adjust', 'sigal.plugins.copyright']
 copyright = u"© An example copyright message"
 adjust_options = {'color': 0.0, 'brightness': 1.0,
                   'contrast': 1.0, 'sharpness': 0.0}