Add docs for subcommands

docs/narr/cli/commands.rst

@@ -6,12 +6,19 @@ Top-level :term:`commands<command>` are primarily a way to group
 :term:`subcommands<subcommand>`.
 
 
+.. _running-commands:
+
 Running a Command
 -----------------
 
 Top-level commands are installed in such a way that they are available
 within the ``bin`` folder of the virtual environment.  (Or the
-``Scripts`` folder if on Windows.)
+``Scripts`` folder if on Windows.)  For instance:
+
+.. code-block:: sh
+
+   cd /path/to/venv
+   bin/wutta --help
 
 This folder should be in the ``PATH`` when the virtual environment is
 activated, in which case you can just run the command by name, e.g.:
@@ -64,6 +71,8 @@ subcommands.
    :returncode: 1
 
 
+.. _adding-commands:
+
 Adding a New Command
 --------------------
 
@@ -87,8 +96,8 @@ First create your :class:`~wuttjamaican.cmd.base.Command` class, and a
        cmd.run(*args)
 
 Then register the :term:`entry point(s)<entry point>` in your
-``setup.cfg``.  The command name should not contain spaces but may
-include hyphens or underscore etc.
+``setup.cfg``.  The command name should *not* contain spaces but *may*
+include hyphen or underscore.
 
 You can register more than one top-level command if needed; these
 could refer to the same ``main()`` function (in which case they
@@ -109,3 +118,6 @@ available:
    cd /path/to/venv
    bin/poser --help
    bin/wutta-poser --help
+
+You will then likely want to add subcommand(s) for this to be useful;
+see :ref:`adding-subcommands`.

docs/narr/cli/scripts.rst

@@ -10,6 +10,9 @@ A script is just a text file with Python code.  To run it you
 generally must invoke the Python interpreter somehow and explicitly
 tell it the path to your script.
 
+Note that a script is (usually) not installed as part of a package.
+They can live anywhere.
+
 Below we'll walk through creating a script.
 
 
@@ -72,6 +75,14 @@ that this also gives you access to the :term:`app handler`::
        config = make_config('my.conf')
        hello(config)
 
+Output should now be different:
+
+.. code-block:: sh
+
+   $ python hello.py
+   hello George
+   from wutta
+
 You are likely to need more imports; it is generally wise to do those
 *within the function* as opposed to the top of the module.  This is to
 ensure the :func:`~wuttjamaican.conf.make_config()` call happens
@@ -94,14 +105,6 @@ before all packages are imported::
        config = make_config('my.conf')
        hello(config)
 
-Output should now be different:
-
-.. code-block:: sh
-
-   $ python hello.py
-   hello George
-   from wutta
-
 
 Logging
 -------

docs/narr/cli/subcommands.rst

@@ -2,4 +2,91 @@
 Subcommands
 ===========
 
-TODO
+A top-level :term:`command` may have multiple
+:term:`subcommands<subcommand>`.
+
+The top-level command is responsible for invoking the subcommand, but
+the subcommand is responsible for performing some action(s).
+
+There is no restriction on what sort of action that might be, but for
+sake of clarity it is best to make a distinct subcommand for each
+"type" of action needed by the app.
+
+
+Running a Subcommand
+--------------------
+
+You cannot run a subcommand directly; you must run a top-level command
+and specify the subcommand as part of the command line arguments.  See
+:ref:`running-commands`.
+
+This restriction holds true even when running a subcommand "natively"
+from within Python code.  For more info see
+:meth:`wuttjamaican.cmd.base.Subcommand.run()`.
+
+
+Built-in Subcommands
+--------------------
+
+WuttJamaican comes with one top-level command named ``wutta`` as well
+as a few subcommands under that.
+
+See :mod:`wuttjamaican.cmd` for more on the built-in ``wutta``
+subcommands.
+
+
+.. _adding-subcommands:
+
+Adding a New Subcommand
+-----------------------
+
+There are two steps for this:
+
+* define the subcommand
+* register it under top-level command(s)
+
+First create a Subcommand class (e.g. by adding to
+``poser/commands.py``)::
+
+   from wuttjamaican.cmd import Subcommand
+
+   class Hello(Subcommand):
+       """
+       Say hello to the user
+       """
+       name = 'hello'
+       description = __doc__.strip()
+
+       def add_args(self):
+           self.parser.add_argument('--foo', default='bar', help="Foo value")
+
+       def run(self, args):
+           print("hello, foo value is:", args.foo)
+
+You may notice there is nothing in that subcommand definition which
+ties it to the ``poser`` top-level command.  That is done by way of
+another :term:`entry point` in your ``setup.cfg`` file.
+
+As with top-level commands, you can "alias" the same subcommand so
+it appears under multiple top-level commands.  Note that if the
+top-level command name contains a hyphen, that must be replaced
+with underscore for sake of the subcommand entry point:
+
+.. code-block:: ini
+
+   [options.entry_points]
+
+   poser.subcommands =
+       hello = poser.commands:Hello
+
+   wutta_poser.subcommands =
+       hello = poser.commands:Hello
+
+Next time your ``poser`` package is installed, the subcommand will be
+available, so you can e.g.:
+
+.. code-block:: sh
+
+   cd /path/to/venv
+   bin/poser hello --help
+   bin/wutta-poser hello --help