From 0838cdb93ca984d6d309dbb84cd8ec06d94a719e Mon Sep 17 00:00:00 2001
From: Lance Edgar <lance@edbob.org>
Date: Mon, 1 Jul 2024 10:53:58 -0500
Subject: [PATCH] update docs for commands, scripts

per changes regarding typer, wuttjamaican etc.
---
 docs/base/commands.rst | 21 +++++++++------------
 docs/base/scripts.rst  | 21 ++++++++++++++-------
 2 files changed, 23 insertions(+), 19 deletions(-)

diff --git a/docs/base/commands.rst b/docs/base/commands.rst
index 10bcefc..9d405cf 100644
--- a/docs/base/commands.rst
+++ b/docs/base/commands.rst
@@ -16,32 +16,29 @@ 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).
+   bin/rattail make-uuid
 
 
 Getting Help
 ------------
 
-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.
+You can always just add ``--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
+To get help on the command proper, add ``--help`` to your command line but omit the
 subcommand, e.g.::
 
-   bin/rattail -c app/quiet.conf -h
+   bin/rattail --help
 
 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::
+were running it, then also add ``--help`` to the command line::
 
-   bin/rattail -c app/quiet.conf make-uuid -h
+   bin/rattail make-uuid --help
 
 
 Usage with ``sudo``
@@ -51,7 +48,7 @@ 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
+   sudo -u rattail bin/rattail make-uuid
 
 Among other things this may be necessary so that:
 
diff --git a/docs/base/scripts.rst b/docs/base/scripts.rst
index 17b2945..ee4d388 100644
--- a/docs/base/scripts.rst
+++ b/docs/base/scripts.rst
@@ -25,6 +25,8 @@ Python Scripts
 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.
 
+(See also :doc:`wuttjamaican:narr/cli/scripts` for more simple examples.)
+
 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
@@ -44,14 +46,21 @@ main function, instead of at the top of the script.
 
 
    def do_something(config):
+
        # most imports should not happen until config is made
-       from rattail.db import Session
+       from rattail.db.auth import administrator_role
+
+       app = config.get_app()
+       model = app.model
 
        # open db connection
-       model = config.get_model()
-       session = Session()
+       session = app.make_session()
 
-       # do something...for instance count the departments
+       # not doing anything useful here, just an example
+       admin = administrator_role(session)
+       print(admin)
+
+       # do something else...for instance count the departments
        print(session.query(model.Department).count())
 
        # must commit session to save any changes
@@ -85,10 +94,8 @@ running it would look like:
 .. code-block:: sh
 
    cd /srv/envs/poser
-   bin/python app/foo.py --help
+   bin/python3 app/foo.py --help
 
-TODO: It seems like Rattail should have a way of generating a skeleton script
-like the above.
 
 Shell Scripts
 -------------