Add basic "config" concept doc

docs/concepts/config.rst

@@ -4,4 +4,112 @@ Configuration
 
 .. contents:: :local:
 
-TODO
+Configuration for an app can come from two sources: configuration file(s), and
+the Settings table in the database.
+
+
+Config File Inheritance
+-----------------------
+
+An important thing to understand regarding Rattail config files, is that one
+file may "include" another file(s), which in turn may "include" others etc.
+Invocation of the app will often require only a single config file to be
+specified, since that file may include others as needed.
+
+For example ``web.conf`` will typically include ``rattail.conf`` but the web
+app need only be invoked with ``web.conf`` - config from both files will inform
+the app's behavior.
+
+
+Typical Config Files
+--------------------
+
+A typical Poser (Rattail-based) app will have at the very least, one file named
+``rattail.conf`` - this is considered the most fundamental config file.  It
+will usually define database connections, logging config, and any other "core"
+things which would be required for any invocation of the app, regardless of the
+environment (e.g. console vs. web).
+
+Note that even ``rattail.conf`` is free to include other files.  This may be
+useful for instance, if you have a single site-wide config file which is shared
+among all Rattail apps.
+
+There is no *strict* requirement for having a ``rattail.conf`` file, but these
+docs will assume its presence.  Here are some other typical files, which the
+docs also may reference occasionally:
+
+**web.conf** - This is the "core" config file for the web app, although it
+still includes the ``rattail.conf`` file.  In production (running on Apache
+etc.) it is specified within the WSGI module which is responsible for
+instantiating the web app.  When running the development server, it is
+specified via command line.
+
+**quiet.conf** - This is a slight wrapper around ``rattail.conf`` for the sake
+of a "quieter" console, when running app commands via console.  It may be used
+in place of ``rattail.conf`` - i.e. you would specify ``-c quiet.conf`` when
+running the command.  The only function of this wrapper is to set the level to
+INFO for the console logging handler.  In practice this hides DEBUG logging
+messages which are shown by default when using ``rattail.conf`` as the app
+config file.
+
+**cron.conf** - Another wrapper around ``rattail.conf`` which suppresses
+logging even further.  The idea is that this config file would be used by cron
+jobs; that way the only actual output is warnings and errors, hence cron would
+not send email unless something actually went wrong.  It may be used in place
+of ``rattail.conf`` - i.e. you would specify ``-c cron.conf`` when running the
+command.  The only function of this wrapper is to set the level to WARNING for
+the console logging handler.
+
+**ignore-changes.conf** - This file is only relevant if your ``rattail.conf``
+says to "record changes" when write activity occurs in the database(s).  Note
+that this file does *not* include ``rattail.conf`` because it is meant to be
+supplemental only.  For instance on the command line, you would need to specify
+two config files, first ``rattail.conf`` or a suitable alternative, but then
+``ignore-changes.conf`` also.  If specified, this file will cause changes to be
+ignored, i.e. **not recorded** when write activity occurs.
+
+**without-versioning.conf** - This file is only relevant if your
+``rattail.conf`` says to enable "data versioning" when write activity occurs in
+the database(s).  Note that this file does *not* include ``rattail.conf``
+because it is meant to be supplemental only.  For instance on the command line,
+you would need to specify two config files, first ``rattail.conf`` or a
+suitable alternative, but then ``without-versioning.conf`` also.  If specified,
+this file will disable the data versioning system entirely.  Note that if
+versioning is undesirable for a given app run, this is the only way to
+effectively disable it; once loaded that feature cannot be disabled.
+
+
+Settings from Database
+----------------------
+
+The other (often more convenient) source of app configuration is the Settings
+table within the app database.  Whether or not this table is a valid source for
+app configuration, ultimately depends on what the config file(s) has to say
+about it.
+
+Assuming the config file(s) defines a database connection and declares it a
+valid source for config values, then the Settings table may contribute to the
+running app config.  The nice thing about this is that these settings are
+checked in real-time.  So whereas changing a config file will require an app
+restart, any edits to the settings table should take effect immediately.
+
+Usually the settings table will *override* values found in the config file.
+This behavior also is configurable to some extent, and in some cases a config
+value may *only* come from a config file and never the settings table.
+
+An example may help here.  If the config file contained the following value:
+
+.. code-block:: ini
+
+   [poser]
+   foo = bar
+
+Then you could create a new Setting in the database with the following fields:
+
+* **name** = poser.foo
+* **value** = baz
+
+Assuming typical setup, i.e. where settings table may override config file, the
+app would consider 'baz' to be the config value.  So basically the setting name
+must correspond to a combination of the config file "section" name, then a dot,
+then the "option" name.

docs/concepts/console.rst

@@ -0,0 +1,7 @@
+
+Console Commands
+================
+
+.. contents:: :local:
+
+TODO

docs/index.rst

@@ -27,6 +27,8 @@ Concept Guide:
 .. toctree::
 
    concepts/config
+   ..
+      concepts/console
    concepts/schema
    concepts/batches