Add docs for new batch system.

And some other tweak(s).

docs/narr/batches.rst

@@ -0,0 +1,74 @@
+.. -*- coding: utf-8 -*-
+
+Data Batches
+============
+
+This document briefly outlines what comprises a batch in terms of the Tailbone
+user interface etc.
+
+
+Batch Views
+-----------
+
+Adding support for a new batch type is mostly a matter of providing some custom
+views for the batch and its rows.  In fact you must define four different view
+classes, inheriting from each of the following:
+
+* :class:`tailbone.views.batch.BatchGrid`
+* :class:`tailbone.views.batch.BatchCrud`
+* :class:`tailbone.views.batch.BatchRowGrid`
+* :class:`tailbone.views.batch.BatchRowCrud`
+
+It would sure be nice to only require two view classes instead of four, hopefully
+that can happen "soon".  In the meantime that's what it takes.  Note that as with
+batch data models, there are some more specialized parent classes which you may
+want to inherit from instead of the core classes mentioned above:
+
+* :class:`tailbone.views.batch.FileBatchGrid`
+* :class:`tailbone.views.batch.FileBatchCrud`
+* :class:`tailbone.views.batch.ProductBatchRowGrid`
+
+Here are the vendor catalog views as examples:
+
+* :class:`tailbone.views.vendors.catalogs.VendorCatalogGrid`
+* :class:`tailbone.views.vendors.catalogs.VendorCatalogCrud`
+* :class:`tailbone.views.vendors.catalogs.VendorCatalogRowGrid`
+* :class:`tailbone.views.vendors.catalogs.VendorCatalogRowCrud`
+
+
+Pyramid Config
+--------------
+
+In addition to defining the batch views, the Pyramid Configurator object must be
+told of the views and their routes.  This also could probably stand to be simpler
+somehow, but for now the easiest thing is to apply default configuration with:
+
+* :func:`tailbone.views.batch.defaults()`
+
+See the source behind the vendor catalog for an example:
+
+* :func:`tailbone.views.vendors.catalogs.includeme()`
+
+Note of course that your view config must be included by the core/upstream
+config process of your application's startup to take effect.  At this point
+your views should be accessible by navigating to the URLs directly, e.g. for
+the vendor catalog views:
+
+* List Uploaded Catalogs - http://example.com/vendors/catalogs/
+* Upload New Catlaog - http://example.com/vendors/catalogs/new
+
+
+Menu and Templates
+------------------
+
+Providing access to the batch views is (I think) the last step.  You must add
+links to the views, wherever that makes sense for your app.  In case it's
+helpful, here's a Mako template snippet which would show some links to the main
+vendor catalog views:
+
+.. code-block:: mako
+
+   <ul>
+     <li>${h.link_to("Vendor Catalogs", url('vendors.catalogs'))}</li>
+     <li>${h.link_to("Upload new Vendor Catalog", url('vendors.catalogs.create'))}</li>
+   </ul>