Commits

Andy Mikhailenko committed 1fce951

Re issue #24: updated documentation to match the refactored state of code.

Comments (0)

Files changed (10)

 #  Software Foundation. See the file README for copying conditions.
 #
 """
-API reference
-=============
-
-.. automodule:: argh.decorators
-   :members:
-
-.. automodule:: argh.assembling
-   :members:
-
-.. automodule:: argh.dispatching
-   :members:
-
-.. automodule:: argh.completion
-   :members:
-
-.. automodule:: argh.helpers
-   :members:
-
-.. automodule:: argh.exceptions
-   :members:
-
-.. automodule:: argh.io
-   :members:
-
-.. automodule:: argh.utils
-   :members:
-
+Argh
+====
 """
 from .assembling import *
 from .decorators import *

argh/assembling.py

 def set_default_command(parser, function):
     """ Sets default command (i.e. a function) for given parser.
 
-    If `parser.description` is empty and the function has a docstring, it is
-    used as the description.
+    If `parser.description` is empty and the function has a docstring,
+    it is used as the description.
 
     .. note::
 
        An attempt to set default command to a parser which already has
-       subparsers (e.g. added with :func:`~argh.helpers.add_commands`)
+       subparsers (e.g. added with :func:`~argh.assembling.add_commands`)
        results in a `RuntimeError`.
 
     """
 
     :param functions:
 
-        a list of functions. A subparser is created for each of them. If the
-        function is decorated with :func:`arg`, the arguments are passed to
-        the :class:`~argparse.ArgumentParser.add_argument` method of the
-        parser. See also :func:`dispatch` for requirements concerning function
-        signatures. The command name is inferred from the function name. Note
-        that the underscores in the name are replaced with hyphens, i.e.
-        function name "foo_bar" becomes command name "foo-bar".
+        a list of functions. A subparser is created for each of them.
+        If the function is decorated with :func:`~argh.decorators.arg`, the
+        arguments are passed to :class:`argparse.ArgumentParser.add_argument`.
+        See also :func:`~argh.dispatching.dispatch` for requirements
+        concerning function signatures. The command name is inferred from the
+        function name. Note that the underscores in the name are replaced with
+        hyphens, i.e. function name "foo_bar" becomes command name "foo-bar".
 
     :param namespace:
 
 
         This function modifies the parser object. Generally side effects are
         bad practice but we don't seem to have any choice as ArgumentParser is
-        pretty opaque. You may prefer :class:`ArghParser.add_commands` for a
-        bit more predictable API.
+        pretty opaque.
+        You may prefer :class:`~argh.helpers.ArghParser.add_commands` for a bit
+        more predictable API.
 
     .. admonition:: Design flaw
 
     .. note::
 
        An attempt to add commands to a parser which already has a default
-       function (e.g. added with :func:`~argh.helpers.set_default_command`)
+       function (e.g. added with :func:`~argh.assembling.set_default_command`)
        results in a `RuntimeError`.
 
     """

argh/completion.py

 Shell completion
 ================
 
-... warning::
-
-    TODO: describe how to install
+.. warning:: TODO: describe how to install
 
 """
 import sys
 
 
 def autocomplete(root_parser):
+    """ Prints shell completion choices.
+    """
     if not os.environ.get('ARGH_AUTO_COMPLETE'):
         return
 
 
     sys.exit(1)
 
+
 def _autocomplete(root_parser, cwords, cword):
 
     def _collect_choices(parser, word):

argh/decorators.py

 
 
 def wrap_errors(*exceptions):
-    """Decorator. Wraps given exceptions into :class:`CommandError`. Usage::
+    """Decorator. Wraps given exceptions into
+    :class:`~argh.exceptions.CommandError`. Usage::
 
         @arg('-x')
         @arg('-y')

argh/dispatching.py

 
     The target function should expect one positional argument: the
     :class:`argparse.Namespace` object. However, if the function is decorated with
-    :func:`plain_signature`, the positional and named arguments from the
-    namespace object are passed to the function instead of the object itself.
+    :func:`~argh.decorators.plain_signature`, the positional and named
+    arguments from the namespace object are passed to the function instead
+    of the object itself.
 
     :param parser:
 
         will also need to install it.)
 
     By default the exceptions are not wrapped and will propagate. The only
-    exception that is always wrapped is :class:`CommandError` which is
-    interpreted as an expected event so the traceback is hidden. You can also
-    mark arbitrary exceptions as "wrappable" by using the :func:`wrap_errors`
-    decorator.
+    exception that is always wrapped is :class:`~argh.exceptions.CommandError`
+    which is interpreted as an expected event so the traceback is hidden.
+    You can also mark arbitrary exceptions as "wrappable" by using the
+    :func:`~argh.decorators.wrap_errors` decorator.
     """
     if completion:
         autocomplete(parser)
 def _execute_command(args):
     """Asserts that ``args.function`` is present and callable. Tries different
     approaches to calling the function (with an `argparse.Namespace` object or
-    with ordinary signature). Yields the results line by line. If CommandError
-    is raised, its message is appended to the results (i.e. yielded by the
-    generator as a string). All other exceptions propagate unless marked as
-    wrappable by :func:`wrap_errors`.
+    with ordinary signature). Yields the results line by line.
+
+    If :class:`~argh.exceptions.CommandError` is raised, its message is
+    appended to the results (i.e. yielded by the generator as a string).
+    All other exceptions propagate unless marked as wrappable
+    by :func:`wrap_errors`.
     """
     assert hasattr(args, 'function') and hasattr(args.function, '__call__')
 
         parser.set_default_command(foo)
         parser.dispatch()
 
-    This function can also be used as a decorator. Here's a more or less
-    sensible example::
-
-        from argh import *
-
-        @dispatch_command
-        @arg('name')
-        def main(args):
-            return args.name
-
+    This function can be also used as a decorator.
     """
     parser = argparse.ArgumentParser()
     set_default_command(parser, function)
 
 
 class ArghParser(argparse.ArgumentParser):
-    """An :class:`ArgumentParser` subclass which adds a couple of convenience
+    """ A subclass of :class:`ArgumentParser` with a couple of convenience
     methods.
 
     There is actually no need to subclass the parser. The methods are but
-    wrappers for stand-alone functions :func:`add_commands` ,
-    :func:`autocomplete` and :func:`dispatch`.
+    wrappers for stand-alone functions :func:`~argh.assembling.add_commands`,
+    :func:`~argh.completion.autocomplete` and
+    :func:`~argh.dispatching.dispatch`.
     """
     def set_default_command(self, *args, **kwargs):
         "Wrapper for :func:`set_default_command`."
 
 
 def get_subparsers(parser, create=False):
-    """Returns the :class:`argparse._SupParsersAction` instance for given
+    """Returns the :class:`argparse._SubParsersAction` instance for given
     :class:`ArgumentParser` instance as would have been returned by
     :meth:`ArgumentParser.add_subparsers`. The problem with the latter is that
     it only works once and raises an exception on the second attempt, and the
   :class:`argparse.Namespace` object.
 
 `Argh` is fully compatible with `argparse`. You can mix `argh`-agnostic and
-`argh`-aware code. Just keep in mind that :func:`~argh.helpers.dispatch` does
-some extra work that a custom dispatcher may not do.
+`argh`-aware code. Just keep in mind that :func:`~argh.dispatching.dispatch`
+does some extra work that a custom dispatcher may not do.
 
 Dependencies
 ------------

docs/reference.rst

+API Reference
+=============
+
 .. automodule:: argh
    :members:
+
+.. automodule:: argh.decorators
+   :members:
+
+.. automodule:: argh.assembling
+   :members:
+
+.. automodule:: argh.dispatching
+   :members:
+
+.. automodule:: argh.completion
+   :members:
+
+.. automodule:: argh.helpers
+   :members:
+
+.. automodule:: argh.exceptions
+   :members:
+
+.. automodule:: argh.io
+   :members:
+
+.. automodule:: argh.utils
+   :members:

docs/tutorial.rst

 can be mixed. It is always possible to declare a command with the highest
 possible (and least flexible) layer — the :func:`~argh.decorators.command`
 decorator — and then tune the behaviour with any of the lower layers:
-:func:`~argh.decorators.arg`, :func:`~argh.helpers.add_commands`,
-:func:`~argh.helpers.dispatch` or directly via the `argparse` API.
+:func:`~argh.decorators.arg`, :func:`~argh.assembling.add_commands`,
+:func:`~argh.dispatching.dispatch` or directly via the `argparse` API.
 
 Dive in
 -------
 
 We have just created a couple of *subcommands* under the namespace "www". The
 `title` keyword is for documentation purposes (see
-:func:`~argh.helpers.add_commands` documentation).
+:func:`~argh.assembling.add_commands` documentation).
 
 The last thing is to actually parse the arguments and call the relevant command
 (function) when our module is called as a script::
     $ ./prog.py www serve-rest
     $ ./prog.py www serve --port 6060 --noreload
 
-There's also a shortcut :func:`~argh.helpers.dispatch_commands` which isn't as
-flexible as the full version described above but helps reduce the code in many
-cases.  Please refer to the API documentation for details.
+There's also a shortcut :func:`~argh.dispatching.dispatch_commands` which
+isn't as flexible as the full version described above but helps reduce
+the code in many cases.  Please refer to the API documentation for details.
 
 Single-command application
 --------------------------
 There are cases when the application performs a single task and it perfectly
 maps to a single command. The method above would require the user to type a
 command like ``check_mail.py check --now`` while ``check_mail.py --now`` would
-suffice. In such cases :func:`~argh.helpers.add_commands` should be replaced with
-:func:`~argh.helpers.set_default_command`::
+suffice. In such cases :func:`~argh.assembling.add_commands` should be replaced
+with :func:`~argh.assembling.set_default_command`::
 
     def main(args):
         return 1
     parser = ArghParser()
     parser.set_default_command(main)
 
-There's also a nice shortcut :func:`~argh.helpers.dispatch_command`.
+There's also a nice shortcut :func:`~argh.dispatching.dispatch_command`.
 Please refer to the API documentation for details.
 
 Subparsers
             return item
 
 `Argh` will wrap this exception and choose the right way to display its
-message (depending on how :func:`~argh.helpers.dispatch` was called).
+message (depending on how :func:`~argh.dispatching.dispatch` was called).
 
-The decorator :func:`~argh.helpers.wrap_errors` reduces the code even further::
+The decorator :func:`~argh.decorators.wrap_errors` reduces the code even further::
 
     @arg('key')
     @wrap_errors(KeyError)        # catch KeyError, show the message, hide traceback