Merge branch '772-document-plugin-load-order'

doc/configuration.rst

@@ -508,6 +508,33 @@ Specify which CKAN plugins are to be enabled.
 
 Format as a space-separated list of the plugin names. The plugin name is the key in the ``[ckan.plugins]`` section of the extension's ``setup.py``. For more information on plugins and extensions, see :doc:`extensions/index`.
 
+.. note::
+
+    The order of the plugin names in the configuration file influences the
+    order that CKAN will load the plugins in. As long as each plugin class is
+    implemented in a separate Python module (i.e. in a separate Python source
+    code file), the plugins will be loaded in the order given in the
+    configuration file.
+
+    When multiple plugins are implemented in the same Python module, CKAN will
+    process the plugins in the order that they're given in the config file, but as
+    soon as it reaches one plugin from a given Python module, CKAN will load all
+    plugins from that Python module, in the order that the plugin classes are
+    defined in the module.
+
+    For simplicity, we recommend implementing each plugin class in its own Python
+    module.
+
+    Plugin loading order can be important, for example for plugins that add custom
+    template files: templates found in template directories added earlier will
+    override templates in template directories added later.
+
+    .. todo::
+
+        Fix CKAN's plugin loading order to simply load all plugins in the order
+        they're given in the config file, regardless of which Python modules
+        they're implemented in.
+
 .. _ckan.datastore.enabled:
 
 ckan.datastore.enabled

doc/extensions/best-practices.rst

@@ -1,14 +1,18 @@
--------------------------------------
+=====================================
 Best practices for writing extensions
--------------------------------------
+=====================================
 
+
+------------------------------
 Follow CKAN's coding standards
-==============================
+------------------------------
 
 See :ref:`coding standards`.
 
+
+-------------------------------------------------
 Use the plugins toolkit instead of importing CKAN
-=================================================
+-------------------------------------------------
 
 Try to limit your extension to interacting with CKAN only through CKAN's
 :doc:`plugin interfaces <plugin-interfaces>` and
@@ -17,10 +21,17 @@ extension code separate from CKAN as much as possible, so that internal changes
 in CKAN from one release to the next don't break your extension.
 
 
+---------------------------------
 Don't edit CKAN's database tables
-=================================
+---------------------------------
 
 An extension can create its own tables in the CKAN database, but it should *not*
 write to core CKAN tables directly, add columns to core tables, or use foreign
 keys against core tables.
 
+
+-------------------------------------------------------
+Implement each plugin class in a separate Python module
+-------------------------------------------------------
+
+This keeps CKAN's plugin loading order simple, see :ref:`ckan.plugins`.