Merge pull request #903 from python-cmd2/completion_docs

Revise completion docs. Fixes #800. Updates #765.

Author: kotfu

docs/features/completion.rst

@@ -1,21 +1,22 @@
 Completion
 ==========
 
-``cmd2`` adds tab completion of file system paths for all built-in commands
-where it makes sense, including:
+:class:`cmd2.Cmd` adds tab completion of file system paths for all built-in
+commands where it makes sense, including:
 
-- ``edit``
-- ``run_pyscript``
-- ``run_script``
-- ``shell``
+- :ref:`features/builtin_commands:edit`
+- :ref:`features/builtin_commands:run_pyscript`
+- :ref:`features/builtin_commands:run_script`
+- :ref:`features/builtin_commands:shell`
 
-``cmd2`` also adds tab completion of shell commands to the ``shell`` command.
+:class:`cmd2.Cmd` also adds tab completion of shell commands to the
+:ref:`features/builtin_commands:shell` command.
 
-Additionally, it is trivial to add identical file system path completion to
-your own custom commands.  Suppose you have defined a custom command ``foo`` by
-implementing the ``do_foo`` method.  To enable path completion for the ``foo``
-command, then add a line of code similar to the following to your class which
-inherits from ``cmd2.Cmd``::
+It is easy to add identical file system path completion to your own custom
+commands.  Suppose you have defined a custom command ``foo`` by implementing
+the ``do_foo`` method.  To enable path completion for the ``foo`` command, then
+add a line of code similar to the following to your class which inherits from
+:class:`cmd2.Cmd`::
 
     complete_foo = cmd2.Cmd.path_complete
 
@@ -27,7 +28,7 @@ The built-in logic allows for a few more advanced path completion capabilities,
 such as cases where you only want to match directories.  Suppose you have a
 custom command ``bar`` implemented by the ``do_bar`` method.  You can enable
 path completion of directories only for this command by adding a line of code
-similar to the following to your class which inherits from ``cmd2.Cmd``::
+similar to the following to your class which inherits from :class:`cmd2.Cmd`::
 
     # Make sure you have an "import functools" somewhere at the top
     complete_bar = functools.partialmethod(cmd2.Cmd.path_complete, path_filter=os.path.isdir)
@@ -40,19 +41,19 @@ When using one the Argparse-based :ref:`api/decorators:cmd2.decorators`,
 ``cmd2`` provides automatic tab completion of flag names.
 
 Tab completion of argument values can be configured by using one of five
-parameters to ``argparse.ArgumentParser.add_argument()``
+parameters to :meth:`argparse.ArgumentParser.add_argument`
 
 - ``choices``
-- ``choices_function`` / ``choices_method``
-- ``completer_function`` / ``completer_method``
+- ``choices_function`` or ``choices_method``
+- ``completer_function`` or ``completer_method``
 
 See the arg_decorators_ or colors_ example for a demonstration of how to
 use the ``choices`` parameter. See the argparse_completion_ example for a
 demonstration of how to use the ``choices_function`` and ``choices_method``
 parameters. See the arg_decorators_ or argparse_completion_ example for a
 demonstration of how to use the ``completer_method`` parameter.
 
-When tab completing flags and/or argument values for a ``cmd2`` command using
+When tab completing flags or argument values for a ``cmd2`` command using
 one of these decorators, ``cmd2`` keeps track of state so that once a flag has
 already previously been provided, it won't attempt to tab complete it again.
 When no completion results exists, a hint for the current argument will be
@@ -74,4 +75,9 @@ any of the 4 completion functions: ``choices_function``, ``choices_method``,
 ``completion_function``, or ``completion_method``.
 
 See the argparse_completion_ example or the implementation of the built-in
-**set** command for demonstration of how this is used.
+:meth:`~cmd2.Cmd.do_set` command for demonstration of how this is used.
+
+For More Information
+--------------------
+
+See :mod:`cmd2.argparse_custom` for more details.