From 70e538ca605e628c9657e1c0085bff6ec87e1cc6 Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Thu, 7 Jan 2021 21:20:31 -0600 Subject: [PATCH] Add some docs for commands, scripts, available settings --- docs/background.rst | 17 +++++ docs/base/commands.rst | 52 +++++++++++++--- docs/base/config/available/bouncer.rst | 5 ++ docs/base/config/available/common.rst | 5 ++ docs/base/config/available/datasync.rst | 5 ++ docs/base/config/available/db.rst | 5 ++ docs/base/config/available/email.rst | 5 ++ docs/base/config/available/filemon.rst | 5 ++ docs/base/config/available/index.rst | 16 +++++ docs/base/config/available/overview.rst | 18 ++++++ docs/base/config/available/web.rst | 5 ++ docs/base/config/defined.rst | 11 ---- docs/base/config/index.rst | 2 +- docs/base/scripts.rst | 83 ++++++++++++++++++++++++- docs/data/index.rst | 1 + docs/data/versioning.rst | 5 ++ docs/index.rst | 7 ++- 17 files changed, 224 insertions(+), 23 deletions(-) create mode 100644 docs/background.rst create mode 100644 docs/base/config/available/bouncer.rst create mode 100644 docs/base/config/available/common.rst create mode 100644 docs/base/config/available/datasync.rst create mode 100644 docs/base/config/available/db.rst create mode 100644 docs/base/config/available/email.rst create mode 100644 docs/base/config/available/filemon.rst create mode 100644 docs/base/config/available/index.rst create mode 100644 docs/base/config/available/overview.rst create mode 100644 docs/base/config/available/web.rst delete mode 100644 docs/base/config/defined.rst create mode 100644 docs/data/versioning.rst diff --git a/docs/background.rst b/docs/background.rst new file mode 100644 index 0000000..0270e44 --- /dev/null +++ b/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. diff --git a/docs/base/commands.rst b/docs/base/commands.rst index 215f12c..10bcefc 100644 --- a/docs/base/commands.rst +++ b/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 diff --git a/docs/base/config/available/bouncer.rst b/docs/base/config/available/bouncer.rst new file mode 100644 index 0000000..035cb1b --- /dev/null +++ b/docs/base/config/available/bouncer.rst @@ -0,0 +1,5 @@ + +Settings for bouncer +==================== + +TODO diff --git a/docs/base/config/available/common.rst b/docs/base/config/available/common.rst new file mode 100644 index 0000000..6043598 --- /dev/null +++ b/docs/base/config/available/common.rst @@ -0,0 +1,5 @@ + +Common Settings +=============== + +TODO diff --git a/docs/base/config/available/datasync.rst b/docs/base/config/available/datasync.rst new file mode 100644 index 0000000..2f49982 --- /dev/null +++ b/docs/base/config/available/datasync.rst @@ -0,0 +1,5 @@ + +Settings for datasync +===================== + +TODO diff --git a/docs/base/config/available/db.rst b/docs/base/config/available/db.rst new file mode 100644 index 0000000..d98651d --- /dev/null +++ b/docs/base/config/available/db.rst @@ -0,0 +1,5 @@ + +Settings for DB connections +=========================== + +TODO diff --git a/docs/base/config/available/email.rst b/docs/base/config/available/email.rst new file mode 100644 index 0000000..f9ca980 --- /dev/null +++ b/docs/base/config/available/email.rst @@ -0,0 +1,5 @@ + +Settings for email +================== + +TODO diff --git a/docs/base/config/available/filemon.rst b/docs/base/config/available/filemon.rst new file mode 100644 index 0000000..c6017ea --- /dev/null +++ b/docs/base/config/available/filemon.rst @@ -0,0 +1,5 @@ + +Settings for filemon +==================== + +TODO diff --git a/docs/base/config/available/index.rst b/docs/base/config/available/index.rst new file mode 100644 index 0000000..77c8525 --- /dev/null +++ b/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 diff --git a/docs/base/config/available/overview.rst b/docs/base/config/available/overview.rst new file mode 100644 index 0000000..d60abe3 --- /dev/null +++ b/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`. diff --git a/docs/base/config/available/web.rst b/docs/base/config/available/web.rst new file mode 100644 index 0000000..fe76034 --- /dev/null +++ b/docs/base/config/available/web.rst @@ -0,0 +1,5 @@ + +Settings for web +================ + +TODO diff --git a/docs/base/config/defined.rst b/docs/base/config/defined.rst deleted file mode 100644 index f03927e..0000000 --- a/docs/base/config/defined.rst +++ /dev/null @@ -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! diff --git a/docs/base/config/index.rst b/docs/base/config/index.rst index 63f6dfd..c020902 100644 --- a/docs/base/config/index.rst +++ b/docs/base/config/index.rst @@ -13,4 +13,4 @@ Configuration generate logging db - defined + available/index diff --git a/docs/base/scripts.rst b/docs/base/scripts.rst index a74882f..17b2945 100644 --- a/docs/base/scripts.rst +++ b/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 ------------- diff --git a/docs/data/index.rst b/docs/data/index.rst index 0826550..b37cda0 100644 --- a/docs/data/index.rst +++ b/docs/data/index.rst @@ -12,6 +12,7 @@ Data Layer importing datasync batches + versioning multinode tempmon tasks diff --git a/docs/data/versioning.rst b/docs/data/versioning.rst new file mode 100644 index 0000000..d212069 --- /dev/null +++ b/docs/data/versioning.rst @@ -0,0 +1,5 @@ + +Data Versioning +=============== + +TODO diff --git a/docs/index.rst b/docs/index.rst index 20b38a6..2b21eab 100644 --- a/docs/index.rst +++ b/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/ +`_ for the latest version of +this document. + .. toctree:: :maxdepth: 2 :caption: Contents: readfirst + background base/index data/index web/index