[#2750] Improve IDatasetForm docstrings

- Rewrite the IDatasetForm docstrings to make them clearer,
  and conform to PEP257
- Reorder methods in IDatasetForm and DefaultDatasetForm
  so that they're 1. in a more logical order and 2. in the
  same order as eachother
- Tell autodoc to put the methods in source-code order,
  not alphabetical, in the sphinx docs
- Remove docstrings from DefaultDatasetForm that are
  exact repeats of corresponding docstrings in IDatasetForm
- Add edit_template() to IDatasetForm, it was missing

db_to_form_schema_options() and form_to_db_schema_options() and some
other schema methods in DefaultDatasetForm are still missing from
IDatasetForm but I'm leaving it that way for now, consider them
unofficial.

ckan/lib/plugins.py

@@ -158,73 +158,43 @@ def register_group_plugins(map):
 
 
 class DefaultDatasetForm(object):
-    """
-    Provides a default implementation of the pluggable package
-    controller behaviour.
+    '''The default implementation of IDatasetForm.
 
-    This class has 2 purposes:
+    See ckan.plugins.interfaces.IDatasetForm.
 
-     - it provides a base class for IDatasetForm implementations to use
-       if only a subset of the 5 method hooks need to be customised.
+    This class has two purposes:
 
-     - it provides the fallback behaviour if no plugin is setup to
-       provide the fallback behaviour.
+    1. It provides a base class for IDatasetForm implementations to inherit
+       from.
+
+    2. It is used as the default fallback plugin, if no IDatasetForm plugin
+       registers itself as the fallback.
 
     Note - this isn't a plugin implementation. This is deliberate, as we
            don't want this being registered.
-    """
-    def new_template(self):
-        """
-        Returns a string representing the location of the template to be
-        rendered for the new page
-        """
-        return 'package/new.html'
 
-    def edit_template(self):
-        """
-        Returns a string representing the location of the template to be
-        rendered for the edit page
-        """
-        return 'package/edit.html'
-
-    def comments_template(self):
-        """
-        Returns a string representing the location of the template to be
-        rendered for the comments page
-        """
-        return 'package/comments.html'
+    '''
+    def form_to_db_schema_options(self, options):
+        '''Return different form_to_db_schemas under different conditions.
 
-    def search_template(self):
-        """
-        Returns a string representing the location of the template to be
-        rendered for the search page (if present)
-        """
-        return 'package/search.html'
+        For example:
 
-    def read_template(self):
-        """
-        Returns a string representing the location of the template to be
-        rendered for the read page
-        """
-        return 'package/read.html'
+        - if a context is provided, and it contains a schema, return that
+          schema
+        - if a dataset is being created via the api then return
+          form_to_db_schema_api_create()
+        - if a dataset is being updated via the api then return
+          form_to_db_schema_api_update()
+        - if a dataset is being created via the web form then return
+          form_to_db_schema()
 
-    def history_template(self):
-        """
-        Returns a string representing the location of the template to be
-        rendered for the history page
-        """
-        return 'package/history.html'
+        The schemas are defined by the methods below.
 
-    def package_form(self):
-        return 'package/new_package_form.html'
+        Because of this method, if an IDatasetForm plugin inherits from this
+        class then its form_to_db_schema() method will only be called when a
+        dataset is being created or updated over the web interface, and not
+        when the api is being used.
 
-    def form_to_db_schema_options(self, options):
-        ''' This allows us to select different schemas for different
-        purpose eg via the web interface or via the api or creation vs
-        updating. It is optional and if not available form_to_db_schema
-        should be used.
-        If a context is provided, and it contains a schema, it will be
-        returned.
         '''
         schema = options.get('context', {}).get('schema', None)
         if schema:
@@ -248,26 +218,28 @@ def form_to_db_schema_api_create(self):
     def form_to_db_schema_api_update(self):
         return logic.schema.default_update_package_schema()
 
-    def db_to_form_schema(self):
-        '''This is an interface to manipulate data from the database
-        into a format suitable for the form (optional)'''
-        return logic.schema.db_to_form_package_schema()
-
     def db_to_form_schema_options(self, options):
-        '''This allows the selectino of different schemas for different
-        purposes.  It is optional and if not available, ``db_to_form_schema``
-        should be used.
-        If a context is provided, and it contains a schema, it will be
-        returned.
+        '''Return different db_to_form_schemas under different conditions.
+
+        For example:
+
+        - if a context is provided, and it contains a schema, return that
+          schema
+        - otherwise return db_to_form_schema()
+
+        The schemas are defined by the methods below.
+
         '''
         schema = options.get('context', {}).get('schema', None)
         if schema:
             return schema
         return self.db_to_form_schema()
 
+    def db_to_form_schema(self):
+        return logic.schema.db_to_form_package_schema()
+
     def check_data_dict(self, data_dict, schema=None):
-        '''Check if the return data is correct, mostly for checking out
-        if spammers are submitting only part of the form'''
+        '''Check for spammers submitting only part of the form.'''
 
         # Resources might not exist yet (eg. Add Dataset)
         surplus_keys_schema = ['__extras', '__junk', 'state', 'groups',
@@ -311,6 +283,27 @@ def setup_template_variables(self, context, data_dict):
             except logic.NotAuthorized:
                 c.auth_for_change_state = False
 
+    def new_template(self):
+        return 'package/new.html'
+
+    def read_template(self):
+        return 'package/read.html'
+
+    def edit_template(self):
+        return 'package/edit.html'
+
+    def comments_template(self):
+        return 'package/comments.html'
+
+    def search_template(self):
+        return 'package/search.html'
+
+    def history_template(self):
+        return 'package/history.html'
+
+    def package_form(self):
+        return 'package/new_package_form.html'
+
 
 class DefaultGroupForm(object):
     """