Merge pull request #720 from python-cmd2/migrating_docs

Write documentation for migrating from cmd

6 files changed, 214 insertions, 3 deletions

diff --git a/docs/features/argument_processing.rst b/docs/features/argument_processing.rst
index 5efc83ef..d0f2c137 100644
--- a/docs/features/argument_processing.rst
+++ b/docs/features/argument_processing.rst
@@ -4,8 +4,9 @@ Argument Processing
 ===================
 
 ``cmd2`` makes it easy to add sophisticated argument processing to your
-commands using the ``argparse`` python module. ``cmd2`` handles the following
-for you:
+commands using the `argparse
+<https://docs.python.org/3/library/argparse.html>`_ python module. ``cmd2``
+handles the following for you:
 
 1. Parsing input and quoted strings like the Unix shell
 
@@ -16,7 +17,9 @@ for you:
    The ``Namespace`` includes the ``Statement`` object that was created when
    parsing the command line. It is stored in the ``__statement__`` attribute of
    the ``Namespace``.
+
 4. Adds the usage message from the argument parser to your command.
+
 5. Checks if the ``-h/--help`` option is present, and if so, display the help
    message for the command
 
diff --git a/docs/features/clipboard.rst b/docs/features/clipboard.rst
index d5048cc0..73e206c2 100644
--- a/docs/features/clipboard.rst
+++ b/docs/features/clipboard.rst
@@ -1,5 +1,33 @@
 Clipboard Integration
 =====================
 
+Nearly every operating system has some notion of a short-term storage area
+which can be accessed by any program. Usually this is called the clipboard, but
+sometimes people refer to it as the paste buffer.
+
+``cmd2`` integrates with the operating system clipboard using the `pyperclip
+<https://github.com/asweigart/pyperclip>`_ module. Command output can be sent
+to the clipboard by ending the command with a greater than symbol:
+
+.. code-block:: text
+
+    mycommand args >
+
+Think of it as though you are redirecting output to an unnamed, ephemeral
+place, you know, like the clipboard. You can also append output to the current
+contents of the clipboard by ending the command with two greater than symbols:
+
+.. code-block:: text
+
+    mycommand arg1 arg2 >>
+
+
+Developers
+----------
+
+If you would like your ``cmd2`` based application to be able to use the
+clipboard in additional or alternative ways, you can use the following methods
+(which work uniformly on Windows, macOS, and Linux).
+
 .. automodule:: cmd2.clipboard
     :members:
diff --git a/docs/features/embedded_python_shells.rst b/docs/features/embedded_python_shells.rst
index ace68877..7e8c027b 100644
--- a/docs/features/embedded_python_shells.rst
+++ b/docs/features/embedded_python_shells.rst
@@ -1,4 +1,135 @@
 Embedded Python Shells
 ======================
 
-Describe ``py`` and optional ``ipy`` commands
+The ``py`` command will run its arguments as a Python command.  Entered without
+arguments, it enters an interactive Python session.  The session can call
+"back" to your application through the name defined in ``self.pyscript_name``
+(defaults to ``app``).  This wrapper provides access to execute commands in
+your cmd2 application while maintaining isolation.
+
+You may optionally enable full access to to your application by setting
+``locals_in_py`` to ``True``.  Enabling this flag adds ``self`` to the python
+session, which is a reference to your Cmd2 application. This can be useful for
+debugging your application.  To prevent users from enabling this ability
+manually you'll need to remove ``locals_in_py`` from the ``settable``
+dictionary.
+
+The ``app`` object (or your custom name) provides access to application
+commands through raw commands.  For example, any application command call be
+called with ``app("<command>")``.
+
+::
+
+    >>> app('say --piglatin Blah')
+    lahBay
+
+More Python examples:
+
+::
+
+    (Cmd) py print("-".join("spelling"))
+    s-p-e-l-l-i-n-g
+    (Cmd) py
+    Python 3.5.3 (default, Jan 19 2017, 14:11:04)
+    [GCC 6.3.0 20170118] on linux
+    Type "help", "copyright", "credits" or "license" for more information.
+    (CmdLineApp)
+
+    End with `Ctrl-D` (Unix) / `Ctrl-Z` (Windows), `quit()`, `exit()`.
+    Non-python commands can be issued with: app("your command")
+    Run python code from external script files with: run("script.py")
+
+    >>> import os
+    >>> os.uname()
+    ('Linux', 'eee', '2.6.31-19-generic', '#56-Ubuntu SMP Thu Jan 28 01:26:53 UTC 2010', 'i686')
+    >>> app("say --piglatin {os}".format(os=os.uname()[0]))
+    inuxLay
+    >>> self.prompt
+    '(Cmd) '
+    >>> self.prompt = 'Python was here > '
+    >>> quit()
+    Python was here >
+
+Using the ``py`` command is tightly integrated with your main ``cmd2``
+application and any variables created or changed will persist for the life of
+the application::
+
+    (Cmd) py x = 5
+    (Cmd) py print(x)
+    5
+
+The ``py`` command also allows you to run Python scripts via ``py
+run('myscript.py')``. This provides a more complicated and more powerful
+scripting capability than that provided by the simple text file scripts
+discussed in :ref:`scripts`.  Python scripts can include conditional control
+flow logic.  See the **python_scripting.py** ``cmd2`` application and the
+**script_conditional.py** script in the ``examples`` source code directory for
+an example of how to achieve this in your own applications.
+
+Using ``py`` to run scripts directly is considered deprecated.  The newer
+``run_pyscript`` command is superior for doing this in two primary ways:
+
+- it supports tab-completion of file system paths
+- it has the ability to pass command-line arguments to the scripts invoked
+
+There are no disadvantages to using ``run_pyscript`` as opposed to ``py
+run()``.  A simple example of using ``run_pyscript`` is shown below  along with
+the arg_printer_ script::
+
+    (Cmd) run_pyscript examples/scripts/arg_printer.py foo bar baz
+    Running Python script 'arg_printer.py' which was called with 3 arguments
+    arg 1: 'foo'
+    arg 2: 'bar'
+    arg 3: 'baz'
+
+.. note::
+
+    If you want to be able to pass arguments with spaces to commands, then we
+    strongly recommend using one of the decorators, such as
+    ``with_argument_list``.  ``cmd2`` will pass your **do_*** methods a list of
+    arguments in this case.
+
+    When using this decorator, you can then put arguments in quotes like so::
+
+        $ examples/arg_print.py
+        (Cmd) lprint foo "bar baz"
+        lprint was called with the following list of arguments: ['foo', 'bar baz']
+
+.. _arg_printer:
+   https://github.com/python-cmd2/cmd2/blob/master/examples/scripts/arg_printer.py
+
+
+IPython (optional)
+------------------
+
+**If** IPython_ is installed on the system **and** the ``cmd2.Cmd`` class is
+instantiated with ``use_ipython=True``, then the optional ``ipy`` command will
+be present::
+
+    from cmd2 import Cmd
+    class App(Cmd):
+        def __init__(self):
+            Cmd.__init__(self, use_ipython=True)
+
+The ``ipy`` command enters an interactive IPython_ session.  Similar to an
+interactive Python session, this shell can access your application instance via
+``self`` and any changes to your application made via ``self`` will persist.
+However, any local or global variable created within the ``ipy`` shell will not
+persist. Within the ``ipy`` shell, you cannot call "back" to your application
+with ``cmd("")``, however you can run commands directly like so::
+
+    self.onecmd_plus_hooks('help')
+
+IPython_ provides many advantages, including:
+
+    * Comprehensive object introspection
+    * Get help on objects with ``?``
+    * Extensible tab completion, with support by default for completion of
+      python variables and keywords
+
+The object introspection and tab completion make IPython particularly efficient
+for debugging as well as for interactive experimentation and data analysis.
+
+.. _IPython: http://ipython.readthedocs.io
+
+
diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst
index 1dab6f64..5813322b 100644
--- a/docs/features/generating_output.rst
+++ b/docs/features/generating_output.rst
@@ -9,4 +9,37 @@ how to generate output
 - exceptions
 - color support
 
+Output Redirection
+------------------
+
+As in a Unix shell, output of a command can be redirected:
+
+  - sent to a file with ``>``, as in ``mycommand args > filename.txt``
+  - appended to a file with ``>>``, as in ``mycommand args >> filename.txt``
+  - piped (``|``) as input to operating-system commands, as in
+    ``mycommand args | wc``
+
+
+
+.. note::
+
+   If you wish to disable cmd2's output redirection and pipes features, you can
+   do so by setting the ``allow_redirection`` attribute of your ``cmd2.Cmd``
+   class instance to ``False``.  This would be useful, for example, if you want
+   to restrict the ability for an end user to write to disk or interact with
+   shell commands for security reasons::
+
+       from cmd2 import Cmd
+       class App(Cmd):
+           def __init__(self):
+               self.allow_redirection = False
+
+   cmd2's parser will still treat the ``>``, ``>>``, and `|` symbols as output
+   redirection and pipe symbols and will strip arguments after them from the
+   command line arguments accordingly.  But output from a command will not be
+   redirected to a file or piped to a shell command.
+
+If you need to include any of these redirection characters in your command, you
+can enclose them in quotation marks, ``mycommand 'with > in the argument'``.
+
 
diff --git a/docs/features/index.rst b/docs/features/index.rst
index 3087031f..a793efbd 100644
--- a/docs/features/index.rst
+++ b/docs/features/index.rst
@@ -15,6 +15,7 @@ Features
    history
    hooks
    initialization
+   misc
    multiline_commands
    os
    plugins
diff --git a/docs/features/misc.rst b/docs/features/misc.rst
new file mode 100644
index 00000000..4db9f682
--- /dev/null
+++ b/docs/features/misc.rst
@@ -0,0 +1,15 @@
+Miscellaneous Features
+======================
+
+
+Timer
+-----
+
+Turn the timer setting on, and ``cmd2`` will show the wall time it takes for
+each command to execute.
+
+
+Exiting
+-------
+
+Mention quit, exit, and EOF handling built into ``cmd2``.