diff --git a/.gitignore b/.gitignore index 35ebd7fd..906dc226 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ .coverage .tox/ +docs/_build/ htmlcov/ Tailbone.egg-info/ diff --git a/docs/api/views/batch.rst b/docs/api/views/batch.rst new file mode 100644 index 00000000..a98fc39d --- /dev/null +++ b/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 diff --git a/docs/api/views/vendors.catalogs.rst b/docs/api/views/vendors.catalogs.rst new file mode 100644 index 00000000..f45cf27c --- /dev/null +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 09bbd359..572eaceb 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index 19c21af6..f2af6f62 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/narr/batches.rst b/docs/narr/batches.rst new file mode 100644 index 00000000..a3c9b372 --- /dev/null +++ b/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 + + diff --git a/tailbone/views/vendors/catalogs.py b/tailbone/views/vendors/catalogs.py index 5afb4b2a..2a235b5f 100644 --- a/tailbone/views/vendors/catalogs.py +++ b/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/')