Add some about extending the schema, first alembic version

plus some more structure for web/mainapp

docs/data/db/extend.rst

@@ -1,4 +1,6 @@
 
+.. highlight:: sh
+
 Extending the Schema
 ====================
 
@@ -17,4 +19,62 @@ Rattail reserves the prefix-less namespace for its core schema.  Also, certain
 integration packages reserve other namespaces (e.g. ``corepos_`` prefix is used
 by the rattail-corepos package for extension tables it provides).
 
-TODO: obviously need to say how one can go about extending schema...
+
+First Alembic Version
+---------------------
+
+In order to add custom extensions to the schema, you will need to establish
+some things for sake of Alembic.  Note that these steps are only required for
+the "first" extension you add; subsequent versions are somewhat simpler and are
+covered in the next section.
+
+First you should have the basic folder structure::
+
+   cd ~/src/poser
+   mkdir -p poser/db/alembic/versions
+
+You must edit your config file at ``/srv/envs/poser/app/rattail.conf`` and
+update the ``version_locations`` setting for Alembic, to include your new
+folder.  Note the way we specify the path below; this ensures it works no
+matter where things actually live on disk.  Also note that we specify the
+custom location first, core rattail goes last.
+
+.. code-block:: ini
+
+   [alembic]
+   script_location = rattail.db:alembic
+   version_locations = poser.db:alembic/versions rattail.db:alembic/versions
+
+Run a command like this (replacing names etc. as needed) to generate the script
+in your versions folder::
+
+   cd /srv/envs/poser
+   bin/alembic -c app/rattail.conf revision --autogenerate --head rattail@head --version-path ~/src/poser/poser/db/alembic/versions/ -m 'initial Poser tables'
+
+If all goes well that command output should end by telling you where the new
+script lives.  You will want to review this of course, to make sure it includes
+all your new tables.
+
+But you must also declare this version as a new branch head.  This lets your
+custom versions have a life of their own, essentially.  So going forward, when
+you upgrade your DB schema, both the core Rattail tables, as well as your own,
+will be migrated properly.
+
+There are two variables near the top of the script which you must edit, like so:
+
+.. code-block:: python
+
+   down_revision = None
+   branch_labels = ('poser',)
+
+And with all that in place, you can apply the migration to your DB (this part
+is normal)::
+
+   cd /srv/envs/poser
+   bin/alembic -c app/rattail.conf upgrade heads
+
+
+Additional Alembic Versions
+---------------------------
+
+TODO

docs/web/index.rst

@@ -8,6 +8,6 @@ Web Layer
    :caption: Contents:
 
    overview
-   webmain
+   mainapp/index
    webapi
    spa

docs/web/mainapp/index.rst

@@ -0,0 +1,12 @@
+
+Default Web App
+===============
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   overview
+   patterns
+   tasks/index

docs/web/mainapp/overview.rst

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

docs/web/mainapp/patterns.rst

@@ -0,0 +1,6 @@
+
+=================
+ Common Patterns
+=================
+
+TODO

docs/web/mainapp/tasks/index.rst

@@ -0,0 +1,10 @@
+
+Common Tasks
+============
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   newmasterview

docs/web/mainapp/tasks/newmasterview.rst

@@ -0,0 +1,12 @@
+
+===============
+New Master View
+===============
+
+This assumes you already have a table in your (or another) DB and wish to
+expose basic CRUD things for it, a la typical master view style.
+
+If you want to use a custom table you created, you must do that part first.
+See also :doc:`/data/db/extend`.
+
+TODO: how exactly to do it, without copy/pasta

docs/web/webmain.rst

@@ -1,17 +0,0 @@
-
-Default Web App
-===============
-
-TODO
-
-
-Common Tasks
-------------
-
-TODO
-
-
-Common Patterns
----------------
-
-TODO