Add docs for new batch system.

And some other tweak(s).

.gitignore

@@ -1,4 +1,5 @@
 .coverage
 .tox/
+docs/_build/
 htmlcov/
 Tailbone.egg-info/

docs/api/views/batch.rst

@@ -0,0 +1,29 @@
+.. -*- coding: utf-8 -*-
+
+``tailbone.views.batch``
+========================
+
+.. automodule:: tailbone.views.batch
+
+.. autoclass:: BatchGrid
+   :members:
+
+.. autoclass:: FileBatchGrid
+   :members:
+
+.. autoclass:: BatchCrud
+   :members:
+
+.. autoclass:: FileBatchCrud
+   :members:
+
+.. autoclass:: BatchRowGrid
+   :members:
+
+.. autoclass:: ProductBatchRowGrid
+   :members:
+
+.. autoclass:: BatchRowCrud
+   :members:
+
+.. autofunction:: defaults

docs/api/views/vendors.catalogs.rst

@@ -0,0 +1,20 @@
+.. -*- coding: utf-8 -*-
+
+``tailbone.views.vendors.catalogs``
+===================================
+
+.. automodule:: tailbone.views.vendors.catalogs
+
+.. autoclass:: VendorCatalogGrid
+   :members:
+
+.. autoclass:: VendorCatalogCrud
+   :members:
+
+.. autoclass:: VendorCatalogRowGrid
+   :members:
+
+.. autoclass:: VendorCatalogRowCrud
+   :members:
+
+.. autofunction:: includeme

docs/conf.py

@@ -34,6 +34,7 @@ execfile(os.path.join(os.pardir, 'tailbone', '_version.py'))
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.rst

@@ -5,17 +5,32 @@ Tailbone
 Welcome to Tailbone, part of the Rattail project.
 
 The documentation you are currently reading is for the Tailbone web application
-package. More information is (sort of) available at http://rattailproject.org/.
+package.  Some additional information is available on the `website`_.  Clearly
+not everything is documented yet.  Below you can see what has received some
+attention thus far.
 
-Clearly not everything is documented yet.  Below you can see what has received
-some attention thus far.
+.. _website: https://rattailproject.org/
 
-API:
+Narrative Documentation:
 
 .. toctree::
-   :maxdepth: 2
+
+   narr/batches
+
+Package API:
+
+.. toctree::
+   :maxdepth: 1
 
    api/subscribers
+   api/views/batch
+   api/views/vendors.catalogs
+
+
+Documentation To-Do
+===================
+
+.. todolist::
 
 
 Indices and tables

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>

tailbone/views/vendors/catalogs.py

@@ -182,4 +182,7 @@ class VendorCatalogRowCrud(BatchRowCrud):
 
 
 def includeme(config):
+    """
+    Add configuration for the vendor catalog views.
+    """
     defaults(config, VendorCatalogGrid, VendorCatalogCrud, VendorCatalogRowGrid, VendorCatalogRowCrud, '/vendors/catalogs/')