Updated the multiple commands tutorial.

docs/multicommands.rst

@@ -15,7 +15,7 @@ program could have a few auxiliary functions, like verifying the format of a
 config file, or simply displaying the program's version.
 
 
-.. _alt-actions:
+.. _alternate commands:
 
 Alternate actions
 -----------------
@@ -100,16 +100,47 @@ the order they appear in the help.
 Multiple commands
 -----------------
 
-You can specify multiple commands by passing multiple functions to
-:func:`.run`.  Alternative actions are however not compatible with this
-feature.
+This allows you to keep multiple commands under a single program without
+singling one out as the main one. They become available by naming the
+subcommand directly after the program's name on the command line.
+
+Let's see how we can use it in a mock todo list application:
 
 .. literalinclude:: /../examples/multicommands.py
-   :emphasize-lines: 5,13,19-23
+    :lines: 5-15
+
+You can specify multiple commands to run by passing each function as an
+argument to `.run`:
+
+.. code-block:: python
+
+    from clize import run
+
 
-::
+    run(add, list_)
+
+
+.. code-block:: console
+    $ python examples/multicommands.py add A very important note.
+    OK I will remember that.
+    $ python examples/multicommands.py list
+    Sorry I forgot it all :(
 
-    $ python multicommands.py --help
+Alternatively, as with :ref:`alternate commands <alternate commands>`, you can
+pass in an :term:`python:iterable`, a `dict` or an `~collections.OrderedDict`.
+
+Because it isn't passed a regular function with a docstring, Clize can't
+determine an appropriate description from a docstring. You can give it a
+description explicitly with the ``description=`` parameter. Likewise, you an
+add footnotes with the ``footnotes=`` parameter. The format is the same as with
+other docstrings, without the need for documenting parameters.
+
+.. literalinclude:: /../examples/multicommands.py
+    :lines: 18-22
+
+.. code-block:: console
+
+    $ python examples/multicommands.py --help
     Usage: examples/multicommands.py command [args...]
 
     A reliable to-do list utility.
@@ -119,15 +150,7 @@ feature.
     Commands:
       add    Adds an entry to the to-do list.
       list   Lists the existing entries.
-    $ python multicommands.py add A very important note.
-    OK I will remember that.
-    $ python multicommands.py list
-    Sorry I forgot it all :(
-
-Alternatively, you can pass any iterable of functions or a mapping(`dict` or
-`collections.OrderedDict`) to `.run` like with :ref:`the alt parameter
-explained earlier <command-list>`.
-
 
-You'll often need to share a few characteristics between each function. See how
-Clize helps you do that in :ref:`function-compositing`.
+Often, you will need to share a few characteristics, for instance a set of
+parameters, between multiple functions. See how Clize helps you do that in
+:ref:`function-compositing`.

docs/upgrade.rst

@@ -122,9 +122,9 @@ Indicating that an ``*args``-like parameter is required is now done by annotatin
 ___________________________
 
 Alternate actions as shown in Clize 2's tutorial are now done by passing the
-function directly to `.run` :ref:`as shown in the tutorial <alt-actions>`.
-Unlike previously, the alternate command function is passed to the clizer just
-like the main one.
+function directly to `.run` :ref:`as shown in the tutorial <alternate
+commands>`.  Unlike previously, the alternate command function is passed to the
+clizer just like the main one.
 
 For other use cases, you should find the appropriate parameter class from
 `clize.parser` or subclass one, instantiate it and pass it in a sequence as the

examples/altcommands.py

@@ -15,19 +15,5 @@ def version():
     """Show the version"""
     return 'Do Nothing version {0}'.format(VERSION)
 
-def build_date(*,show_time=False):
-    """Show the build date for this version"""
-    print("Build date: 17 August 1979", end='')
-    if show_time:
-        print(" afternoon, about tea time")
-    print()
-
-run(do_nothing, alt={
-        'totally-not-the-version': version,
-        'birthdate': build_date
-        })
-
-run(do_nothing, alt=[version, build_date])
-
 
 run(do_nothing, alt=version)

examples/multicommands.py

@@ -15,9 +15,8 @@ def list_():
     return "Sorry I forgot it all :("
 
 
-if __name__ == '__main__':
-    run(add, list_, description="""
-        A reliable to-do list utility.
+run(add, list_, description="""
+    A reliable to-do list utility.
 
-        Store entries at your own risk.
-        """)
+    Store entries at your own risk.
+    """)