Merge pull request #904 from python-cmd2/scripting_docs

Update scripting docs. Closes #765.

Author: kotfu

docs/api/cmd.rst

@@ -63,3 +63,9 @@ cmd2.Cmd
 
         Set an introduction message which is displayed to the user before
         the :ref:`features/hooks:Command Processing Loop` begins.
+
+    .. attribute:: py_bridge_name
+
+        The symbol name which :ref:`features/scripting:Python Scripts` run
+        using the :ref:`features/builtin_commands:run_pyscript` command can use
+        to reference the parent ``cmd2`` application.

docs/features/builtin_commands.rst

@@ -83,6 +83,15 @@ This command runs commands in a script file that is encoded as either ASCII
 or UTF-8 text.  See :ref:`features/scripting:Command Scripts` for more
 information.
 
+_relative_run_script
+~~~~~~~~~~~~~~~~~~~~
+
+This command is hidden from the help that's visible to end users. It runs a
+script like :ref:`features/builtin_commands:run_script` but does so using a
+path relative to the script that is currently executing. This is useful when
+you have scripts that run other scripts. See :ref:`features/scripting:Running
+Command Scripts` for more information.
+
 set
 ~~~
 

docs/features/scripting.rst

@@ -21,9 +21,10 @@ Creating Command Scripts
 Command scripts can be created in several ways:
 
 - creating a text file using any method of your choice
-- using the built-in ``edit`` command to create or edit an existing text file
-- saving previously entered commands to a script file using ``history -s``. See
-  :ref:`features/history:History` for more details.
+- using the built-in :ref:`features/builtin_commands:edit` command to
+  create or edit an existing text file
+- saving previously entered commands to a script file using
+  :ref:`history -s <features/history:For Users>`
 
 If you create create a text file from scratch, just include one command per
 line, exactly as you would type it inside a ``cmd2`` application.
@@ -32,11 +33,15 @@ line, exactly as you would type it inside a ``cmd2`` application.
 Running Command Scripts
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Command script files can be executed using the built-in ``run_script`` command
-or ``@`` shortcut. Both ASCII and UTF-8 encoded unicode text files are
-supported. The ``run_script`` command supports tab completion of file system
-paths.  There is a variant ``_relative_run_script`` command or ``@@``
-shortcut for use within a script which uses paths relative to the first script.
+Command script files can be executed using the built-in
+:ref:`features/builtin_commands:run_script` command or the ``@`` shortcut (if
+your application is using the default shortcuts). Both ASCII and UTF-8 encoded
+unicode text files are supported. The
+:ref:`features/builtin_commands:run_script` command supports tab completion of
+file system paths.  There is a variant
+:ref:`features/builtin_commands:_relative_run_script` command or ``@@``
+shortcut (if using the default shortcuts) for use within a script which uses
+paths relative to the first script.
 
 
 Comments
@@ -64,26 +69,36 @@ Python Scripts
 
 If you require logic flow, loops, branching, or other advanced features, you
 can write a python script which executes in the context of your ``cmd2`` app.
-This script is run using the ``run_pyscript`` command. A simple example of
-using ``run_pyscript`` is shown below  along with the arg_printer_ script::
+This script is run using the :ref:`features/builtin_commands:run_pyscript`
+command. Here's a simple example that uses the arg_printer_ script::
 
     (Cmd) run_pyscript examples/scripts/arg_printer.py foo bar 'baz 23'
     Running Python script 'arg_printer.py' which was called with 3 arguments
     arg 1: 'foo'
     arg 2: 'bar'
     arg 3: 'baz 23'
 
-``run_pyscript`` supports tab completion of file system paths, and as shown
-above it has the ability to pass command-line arguments to the scripts invoked.
+:ref:`features/builtin_commands:run_pyscript` supports tab completion of file
+system paths, and as shown above it has the ability to pass command-line
+arguments to the scripts invoked.
 
-Python scripts executed with ``run_pyscript`` can run ``cmd2`` application
-commands by using the syntax::
+Python scripts executed with :ref:`features/builtin_commands:run_pyscript` can
+run ``cmd2`` application commands by using the syntax::
 
     app(‘command args’)
 
 where:
 
 * ``app`` is a configurable name which can be changed by setting the
-  ``py_bridge_name`` attribute of your ``cmd2.Cmd`` class instance
-* ``command`` and ``args`` are entered exactly like they would be entered on
-  the command line of your ``cmd2`` application
+  :data:`cmd2.Cmd.py_bridge_name` attribute
+* ``command`` and ``args`` are entered exactly like they would be entered by
+  a user of your application.
+
+.. _python_scripting:
+   https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py
+
+.. _conditional:
+   https://github.com/python-cmd2/cmd2/blob/master/examples/scripts/conditional.py
+
+See python_scripting_ example and associated conditional_ script for more
+information.

examples/python_scripting.py

@@ -1,18 +1,24 @@
 #!/usr/bin/env python
 # coding=utf-8
-"""A sample application for how Python scripting can provide conditional control flow of a cmd2 application.
-
-cmd2's built-in scripting capability, which can be invoked via the "@" shortcut or "run_script" command, uses basic
-ASCII/UTF-8 text scripts and is very easy to use.  Moreover, the trivial syntax of the script files, where there is one
-command per line and the line is exactly what the user would type inside the application, makes it so non-technical
-that end users can quickly learn to create scripts.
-
-However, there comes a time when technical end users want more capability and power.  In particular it is common that
-users will want to create a script with conditional control flow - where the next command run will depend on the results
-from the previous command.  This is where the ability to run Python scripts inside a cmd2 application via the
-run_pyscript command and the "run_pyscript <script> [arguments]" syntax comes into play.
-
-This application and the "scripts/conditional.py" script serve as an example for one way in which this can be done.
+"""A sample application for how Python scripting can provide conditional
+control flow of a cmd2 application.
+
+cmd2's built-in scripting capability, which can be invoked via the "@" shortcut
+or "run_script" command, uses basic ASCII/UTF-8 text scripts and is very easy
+to use.  Moreover, the trivial syntax of the script files, where there is one
+command per line and the line is exactly what the user would type inside the
+application, makes it so non-technical that end users can quickly learn to
+create scripts.
+
+However, there comes a time when technical end users want more capability and
+power.  In particular it is common that users will want to create a script with
+conditional control flow - where the next command run will depend on the
+results from the previous command.  This is where the ability to run Python
+scripts inside a cmd2 application via the run_pyscript command and the
+"run_pyscript <script> [arguments]" syntax comes into play.
+
+This application and the "examples/scripts/conditional.py" script serve as an
+example for one way in which this can be done.
 """
 import argparse
 import os