Add docs for settings table

docs/glossary.rst

@@ -95,7 +95,8 @@ Glossary
 
    settings table
      Table in the :term:`app database` which is used to store
-     :term:`config settings<config setting>`.
+     :term:`config settings<config setting>`.  See also
+     :doc:`narr/config/table`.
 
    subcommand
      A top-level :term:`command` may expose one or more subcommands,

docs/narr/config/index.rst

@@ -9,3 +9,4 @@ Configuration
    settings
    object
    files
+   table

docs/narr/config/overview.rst

@@ -9,7 +9,11 @@ The app must call :func:`~wuttjamaican.conf.make_config()` during
 startup to obtain the config object.
 
 Values come (mostly) from :term:`config files<config file>` and/or the
-:term:`settings table`.  See also :doc:`settings`.
+:term:`settings table`.  For more about those see:
+
+* :doc:`settings`
+* :doc:`files`
+* :doc:`table`
 
 Values are always strings in their raw format, as returned by
 :meth:`~wuttjamaican.conf.WuttaConfig.get()`.  But the config object

docs/narr/config/table.rst

@@ -0,0 +1,74 @@
+
+Settings Table
+==============
+
+Sometimes the :term:`config settings<config setting>` may come from a
+:term:`settings table` as opposed to :term:`config file`.
+
+The settings table resides in the :term:`app database`.
+
+Note that as of writing, the WuttJamaican package *does not address*
+how to create or setup the app database.  However it does have the
+ability to query the settings table if present.
+
+
+Table Structure
+---------------
+
+Currently the table *must* be named ``setting`` and have (at least) 2
+columns, ``name`` and ``value``:
+
+.. code-block:: sql
+
+   CREATE TABLE setting (
+       name VARCHAR(255) NOT NULL PRIMARY KEY,
+       value TEXT
+   );
+
+
+Configuring the DB Connection
+-----------------------------
+
+You must add some entries to your config file, to tell the app where
+its database lives, and that it should be used for this purpose:
+
+.. code-block:: ini
+
+   [wutta.config]
+   usedb = true
+   preferdb = true
+
+   [wutta.db]
+   default.url = postgresql://wutta:wuttapass@localhost/wuttadb
+
+This uses `SQLAlchemy`_ under the hood, so it should support anything
+that does; see also
+:meth:`~wuttjamaican.app.AppHandler.make_engine_from_config()`.
+
+.. _SQLAlchemy: https://www.sqlalchemy.org
+
+See :ref:`where-config-settings-come-from` for more about the
+``usedb`` and ``preferdb`` flags.
+
+
+Querying the Table
+------------------
+
+Normally there is no need to query directly, but rather the
+:term:`config object` may do so automatically.
+
+Assuming the config object knows to look in the settings table, then
+it's just a matter of calling its normal
+:meth:`~wuttjamaican.conf.WuttaConfig.get()` and similar methods::
+
+   from wuttjamaican.conf import make_config
+
+   config = make_config()
+   
+   config.get('foo.bar')
+   config.get_bool('foo.flag')
+
+If your config object does *not* check the settings table by default,
+you can always ask it to explicitly::
+
+   config.get('foo.bar', usedb=True, preferdb=True)

src/wuttjamaican/app.py

@@ -104,7 +104,10 @@ class AppHandler:
         Construct a new DB engine from configuration dict.
 
         This is a wrapper around upstream
-        :func:`sqlalchemy:sqlalchemy.engine_from_config()`.
+        :func:`sqlalchemy:sqlalchemy.engine_from_config()`.  For even
+        broader context of the SQLAlchemy
+        :class:`~sqlalchemy:sqlalchemy.engine.Engine` and their
+        configuration, see :doc:`sqlalchemy:core/engines`.
 
         The purpose of the customization is to allow certain
         attributes of the engine to be driven by config, whereas the