Andy Mikhailenko committed cdfc8c0

Improved documentation a little bit.

Comments (0)

Files changed (4)
+Here's the discussion group:
+Real-life usage
+Among applications that use `argh` are Tool_, OrgTool_, Watchdog_, Poni_ and
+more. Well, there's probably no need to keep a complete and up-to-date list.
+Still, please let me know anyway if you use `argh`_ in your project. I'll be
+glad to know. :-)
+.. _Tool:
+.. _OrgTool:
+.. _Watchdog:
+.. _Poni:


     cwords = os.environ['COMP_WORDS'].split()[1:]
-    cword = int(os.environ['COMP_CWORD'])  # XXX do we need this at all?
+    # this is obviously needed when user edits a word in the middle of the
+    # sentence. We don't support it yet but should:
+    cword = int(os.environ['COMP_CWORD'])
     choices = _autocomplete(root_parser, cwords, cword)
     namespace object are passed to the function instead of the object itself.
     :param parser:
         the ArgumentParser instance.
     :param argv:
         a list of strings representing the arguments. If `None`, ``sys.argv``
         is used instead. Default is `None`.
     :param add_help_command:
         if `True`, converts first positional argument "help" to a keyword
         argument so that ``help foo`` becomes ``foo --help`` and displays usage
         information for "foo". Default is `True`.
     :param encoding:
         Encoding for results. If `None`, it is determined automatically.
         Default is `None`.
     :param intercept:
         If `True`, results are returned as strings. If `False`, results are
         printed to stdout. Default is `False`.
     :param completion:
         If `True`, shell tab completion is enabled. Default is `True`. (You
         will also need to install it.)
             result = args.function(args)
         if isinstance(result, (GeneratorType, list, tuple)):
-            # handle iterable results (function marked with @generator decorator)
+            # handle iterable results
             if not encoding:
                 # choose between terminal's and system's preferred encodings
                 if sys.stdout.isatty():
     """A shortcut for typical confirmation prompt.
     :param action:
         a string describing the action, e.g. "Apply changes". A question mark
         will be appended.
     :param default:
         `bool` or `None`. Determines what happens when user hits :kbd:`Enter`
         without typing in a choice. If `True`, default choice is "yes". If
         `False`, it is "no". If `None` the prompt keeps reappearing until user
         types in a choice (not necessarily acceptable) or until the number of
         iteration reaches the limit. Default is `None`.
     :param skip:
         `bool`; if `True`, no interactive prompt is used and default choice is
         returned (useful for batch mode). Default is `False`.


 The equivalent code without `Argh` would be::
-    import sys
     import argparse
     parser = argparse.ArgumentParser()
     parser = ArghParser()
     parser.add_commands([bar, quux], namespace='foo')
-    parser.dispatch() 
+    parser.dispatch()
 It produces a command hierarchy for the command-line expressions ``foo bar``
 and ``foo quux``. This involves "subsubparsers". Without `Argh` you would need