Add more structure for web layer docs

hopefully more content will come sooner than later..

docs/conf.py

@@ -38,6 +38,7 @@ extensions = [
 
 intersphinx_mapping = {
     'rattail': ('https://rattailproject.org/docs/rattail/', None),
+    'tailbone': ('https://rattailproject.org/docs/tailbone/', None),
 }
 
 # Add any paths that contain templates here, relative to this directory.

docs/web/mainapp/dev/forms.rst

@@ -0,0 +1,5 @@
+
+Forms
+=====
+
+TODO

docs/web/mainapp/dev/grids.rst

@@ -0,0 +1,102 @@
+
+Grids
+=====
+
+A "grid" in Tailbone is just a "displayed table" essentially, but may
+have other goodies connected with it, e.g. a set of filters and paging
+info.
+
+The main class is :class:`~tailbone:tailbone.grids.core.Grid` and most
+of the time you'll just use that, with no need to subclass it.
+
+Note that within a :class:`~tailbone:tailbone.views.master.MasterView`
+you can get a reference to the ``Grid`` class via
+:meth:`~tailbone:tailbone.views.master.MasterView.get_grid_factory()`.
+
+
+Types of Grids
+--------------
+
+The ``Grid`` class is used for a few different things, as described
+below.  Some of the features mentioned are described in the next
+section.
+
+Master CRUD w/ DB Table
+~~~~~~~~~~~~~~~~~~~~~~~
+
+By far the most common type is that used by the ``MasterView`` class,
+to expose a given data set for searching, downloading etc.  Usually
+the data set is just a DB table, so columns map directly between the
+table and grid.
+
+This grid usually allows user to specify filters and sorting/paging
+info.
+
+Master CRUD w/out DB Table
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Less common than the above, some ``MasterView`` classes need to expose
+a grid but the data set does not map to a DB table.  Examples of this
+are the Email Settings grid, and the Tables grid.
+
+This grid often does not allow filtering or paging, on account of the
+relative difficulty to implement (read: author is lazy), but often
+does allow basic sorting.
+
+Master "Rows" CRUD
+~~~~~~~~~~~~~~~~~~
+
+Similar to the above, this grid is used by ``MasterView`` to show
+"child row data" when viewing a particular object record.
+
+Like the first, this grid usually allows filter/sort/paging.  The one
+difference in this regard, is the user is not allowed to save default
+settings for the grid.  This is because (per current logic) each grid
+of this type is unique to the parent object, and settings are kept
+separate for each such grid.  So if settings were saved, they still
+would not apply to other grids.
+
+Field Data
+~~~~~~~~~~
+
+This type of grid is used to show a small-ish table of data, within a
+given form field, when viewing a particular object record.  For
+example when viewing a Role, this is how the Users field is displayed.
+
+This grid normally does not allow filters or paging, but in some cases
+may allow basic sorting.
+
+
+Grid Features
+-------------
+
+Here we discuss some possible features a grid may have.
+
+Columns
+~~~~~~~
+
+Obviously a grid has columns.  But a grid may also have some
+"invisible" columns, for sake of the data they contain.  This
+sometimes is needed for other automation etc. in the client-side UI.
+
+TODO: one of these days, grids should let user choose which, and in
+which order, columns are shown.
+
+Sorting
+~~~~~~~
+
+This is arguably the simplest enhancement to make to a grid.  Only a
+visible column may be sorted, but not all of them.  (It depends on the
+nature of the data set etc.)
+
+Paging
+~~~~~~
+
+With sorting comes the possibility of paging the grid data.  (Sorting
+is required for paging, so the results are deterministic.)
+
+Filters
+~~~~~~~
+
+Many grids allow the user to apply a set of filters, to limit which
+data is shown in the grid.

docs/web/mainapp/dev/index.rst

@@ -0,0 +1,15 @@
+
+Development Guide
+=================
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   overview
+   views
+   grids
+   forms
+   patterns
+   tasks/index

docs/web/mainapp/dev/overview.rst

@@ -0,0 +1,12 @@
+
+Overview
+========
+
+Developing features for your web app is meant to be straightforward.
+Here we'll document some of the main points.
+
+Perhaps the most important concepts are:
+
+* :doc:`views`
+* :doc:`grids`
+* :doc:`forms`

docs/web/mainapp/dev/views.rst

@@ -0,0 +1,5 @@
+
+Views
+=====
+
+TODO

docs/web/mainapp/index.rst

@@ -8,5 +8,4 @@ Default Web App
    :caption: Contents:
 
    overview
-   patterns
-   tasks/index
+   dev/index

docs/web/mainapp/overview.rst

@@ -2,4 +2,8 @@
 Overview
 ========
 
-TODO
+Tailbone provides the default web app.  It is standalone
+(server-rendered), and does not use the web API.
+
+See :doc:`dev/index` for help with developing new features for your
+web app.

docs/web/overview.rst

@@ -2,4 +2,16 @@
 Overview
 ========
 
-TODO
+`Tailbone`_ is the Python package which provides most of the web layer
+for the Rattail Project.  In particular it includes the foundations for:
+
+.. _Tailbone: https://pypi.org/project/tailbone/
+
+* main web app, traditional server-side (see :doc:`mainapp/index`)
+* web API for use with client-side apps (see :doc:`webapi`)
+
+`byjove`_ is the Javascript package which provides "some" of the
+components etc. for use with client-side "single-page" apps (see
+:doc:`spa`)).
+
+.. _byjove: https://www.npmjs.com/package/byjove