Add some docs for commands, scripts, available settings

docs/background.rst

@@ -0,0 +1,17 @@
+
+Background
+==========
+
+Here we'll touch on various "background" info regarding the Rattail Project.
+
+What Rattail Is [Not]
+---------------------
+
+For now please see `The Big Tour`_ which is a long-winded description of the
+kinds of features offered by Rattail.
+
+.. _The Big Tour: https://rattailproject.org/moin/TheBigTour
+
+But in a nutshell, the "goal" of the Rattail Project is to provide a common
+foundation for custom apps useful in retail and similar sectors.  Focus is on
+systems integration, data accuracy and automation/convenience.

docs/base/commands.rst

@@ -1,23 +1,59 @@
 
-Running Commands
+.. highlight:: sh
-================
 
-TODO
+Commands
+========
+
+By "commands" here we really mean console commands, e.g. things you might enter
+on a terminal, or run via shell script or cron job.
 
 
 Typical Usage
 -------------
 
-TODO
+Unless there is a specific reason not to, all commands should be ran from the
+root of your virtual environment.  For example this command will generate and
+display a new UUID::
+
+   cd /srv/envs/poser
+   bin/rattail -c app/quiet.conf make-uuid
+
+Also note that in general, you should always specify a config file as part of
+the command line (as shown above).
 
 
-Running as System User
+Getting Help
-----------------------
+------------
 
-TODO
+You can always just add ``-h`` (or ``--help``) to the end of any command line.
+This will render the command "inert" and the only thing it will do, is display
+some help text.
+
+Really there are 2 "layers" to the command framework: commands proper, and
+subcommands.  In the example above, ``bin/rattail`` is the command proper,
+and ``make-uuid`` is the subcommand.
+
+To get help on the command proper, add ``-h`` to your command line but omit the
+subcommand, e.g.::
+
+   bin/rattail -c app/quiet.conf -h
+
+To get help on a subcommand, you must include the subcommand name as though you
+were running it, then also add ``-h`` to the command line::
+
+   bin/rattail -c app/quiet.conf make-uuid -h
 
 
 Usage with ``sudo``
 -------------------
 
-TODO
+If your virtual environment is owned by someone other than yourself, then you
+probably should run commands as that user also::
+
+   cd /srv/envs/poser
+   sudo -u rattail bin/rattail -c app/quiet.conf make-uuid
+
+Among other things this may be necessary so that:
+
+* user has permission to read from config files which may be restricted
+* user has permission to write to log file(s) which may be restricted

docs/base/config/available/bouncer.rst

@@ -0,0 +1,5 @@
+
+Settings for bouncer
+====================
+
+TODO

docs/base/config/available/common.rst

@@ -0,0 +1,5 @@
+
+Common Settings
+===============
+
+TODO

docs/base/config/available/datasync.rst

@@ -0,0 +1,5 @@
+
+Settings for datasync
+=====================
+
+TODO

docs/base/config/available/db.rst

@@ -0,0 +1,5 @@
+
+Settings for DB connections
+===========================
+
+TODO

docs/base/config/available/email.rst

@@ -0,0 +1,5 @@
+
+Settings for email
+==================
+
+TODO

docs/base/config/available/filemon.rst

@@ -0,0 +1,5 @@
+
+Settings for filemon
+====================
+
+TODO

docs/base/config/available/index.rst

@@ -0,0 +1,16 @@
+
+Available Settings
+==================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   overview
+   common
+   email
+   db
+   web
+   datasync
+   filemon
+   bouncer

docs/base/config/available/overview.rst

@@ -0,0 +1,18 @@
+
+Overview
+========
+
+All settings are (usually) optional, meaning the app will fall back to some
+default value if the setting is not found in config.  And you can put
+essentially whatever you like in your config file (or the DB ``setting``
+table), so in that sense "all settings are available".
+
+But what we want to do here is, define certain common ("available") settings
+which any given Poser/Rattail app can leverage if needed, because the logic to
+do so is part of the underlying framework.
+
+We will present each in terms of how they would be defined in a config file, as
+opposed to DB table.  Often you can store the setting in the DB if you prefer,
+but in some cases the setting *must* be stored within a config file, because
+the app logic will only read it from file, and ignore the DB value.  For more
+info see :doc:`../overview` and :doc:`../db`.

docs/base/config/available/web.rst

@@ -0,0 +1,5 @@
+
+Settings for web
+================
+
+TODO

docs/base/config/defined.rst

@@ -1,11 +0,0 @@
-
-Defined Settings
-================
-
-There are a number of config settings which a given Poser/Rattail app may
-leverage.  Most if not all are optional.  We'll try to describe them here.
-
-Note that we will present each in terms of a "section" and "option" pair,
-i.e. using the naming convention found in a config file vs. that of DB.
-
-TODO!

docs/base/config/index.rst

@@ -13,4 +13,4 @@ Configuration
    generate
    logging
    db
-   defined
+   available/index

docs/base/scripts.rst

@@ -2,14 +2,93 @@
 Writing Scripts
 ===============
 
-TODO
+There are 2 types of scripts you may need to write:  Python and shell.
+
+The reason for writing a script is usually for sake of automating some task,
+logic for which is either "not important enough" or perhaps is "too custom" to
+warrant adding it to the app proper.  For instance app upgrade scripts are
+closely tied to the machine/environment on which the app is installed and so
+are kept outside of the app proper.
+
+Which isn't to say, by the way, that these scripts shouldn't be tracked via
+source control.  All scripts needed to manage the app *should* ideally be
+committed to a Git repo somewhere; see :doc:`/deploy/index` for more on that.
+
+As a rule, shell scripts are "simpler" but of course are limited to the
+commands defined by the app (and underlying shell).  Python scripts bring
+maximum flexibility but can sometimes be overkill.
 
 
 Python Scripts
 --------------
 
-TODO
+A "complete" sample Python script is shown below.  It may be more complex than
+you typically need, but hopefully not too bad; modify as you like.
 
+If you use :doc:`/data/versioning` then it is important to "postpone" most
+module imports, until the config has been fully created.  (Even if you don't
+use versioning it's a good habit, in case you ever change your mind.)  This is
+why, in the example below, the import from ``rattail.db`` happens within the
+main function, instead of at the top of the script.
+
+.. code-block:: python
+
+   #!/srv/envs/poser/bin/python3
+   """
+   This script is useful for such and such.
+   """
+
+   import argparse
+
+   from rattail.config import make_config
+
+
+   def do_something(config):
+       # most imports should not happen until config is made
+       from rattail.db import Session
+
+       # open db connection
+       model = config.get_model()
+       session = Session()
+
+       # do something...for instance count the departments
+       print(session.query(model.Department).count())
+
+       # must commit session to save any changes
+       #session.commit()
+       session.close()
+
+
+   if __name__ == '__main__':
+
+       # here we define available command line args
+       parser = argparse.ArgumentParser()
+       parser.add_argument('-c', '--config', metavar='PATH',
+                           action='append', dest='config_paths')
+
+       # here we determine what args caller specified
+       args = parser.parse_args()
+
+       # okay let's make that config, per command line
+       config = make_config(args.config_paths)
+
+       # if you'd rather skip command line parsing altogether,
+       # you can instead do something like this:
+       #config = make_config('/srv/envs/poser/app/quiet.conf')
+
+       # and finally let's do something useful
+       do_something(config)
+
+Let's say you name this script ``foo.py`` and put it in your app dir, so
+running it would look like:
+
+.. code-block:: sh
+
+   cd /srv/envs/poser
+   bin/python app/foo.py --help
+
+TODO: It seems like Rattail should have a way of generating a skeleton script
+like the above.
 
 Shell Scripts
 -------------

docs/data/index.rst

@@ -12,6 +12,7 @@ Data Layer
    importing
    datasync
    batches
+   versioning
    multinode
    tempmon
    tasks

docs/data/versioning.rst

@@ -0,0 +1,5 @@
+
+Data Versioning
+===============
+
+TODO

docs/index.rst

@@ -12,7 +12,7 @@ the `Rattail Tutorial`_.
 
 .. _Rattail Tutorial: https://rattailproject.org/docs/rattail-tutorial/
 
-This manual is primarily organized according to the possible "layers" of a
+This manual is primarily organized around the possible "layers" of a
 Poser/Rattail app:
 
 * :doc:`base/index` - general app install, command line, plus filemon etc.
@@ -22,11 +22,16 @@ Poser/Rattail app:
 * :doc:`deploy/index` - deals with production deployment
 * :doc:`backup/index` - backing up the production system
 
+Please see `https://rattailproject.org/docs/rattail-manual/
+<https://rattailproject.org/docs/rattail-manual/>`_ for the latest version of
+this document.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    readfirst
+   background
    base/index
    data/index
    web/index