Merge pull request #879 from python-cmd2/prompt_docs

Updated Sphinx documentation related to prompt

3 files changed, 51 insertions, 20 deletions

diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst
index e20e8eff..213a14ec 100644
--- a/docs/api/cmd.rst
+++ b/docs/api/cmd.rst
@@ -6,14 +6,26 @@ cmd2.Cmd
 
     .. automethod:: __init__
 
+    .. attribute:: continuation_prompt
+
+      Use as prompt for multiline commands on the 2nd+ line of input.
+      Default: ``>``.
+
+    .. attribute:: default_error
+
+      The error message displayed when a non-existent command is run.
+      Default: ``{} is not a recognized command, alias, or macro``
+
     .. attribute:: help_error
 
       The error message displayed to the user when they request help for a
       command with no help defined.
+      Default:  ``No help on {}``
 
-    .. attribute:: default_error
+    .. attribute:: prompt
 
-      The error message displayed when a non-existent command is run.
+      The prompt issued to solicit input.
+      Default: ``(Cmd)``.
 
     .. attribute:: settable
 
diff --git a/docs/features/multiline_commands.rst b/docs/features/multiline_commands.rst
index 96063867..6e0a4539 100644
--- a/docs/features/multiline_commands.rst
+++ b/docs/features/multiline_commands.rst
@@ -17,9 +17,9 @@ Continuation prompt
 When a user types a :ref:`Multiline Command
 <features/multiline_commands:Multiline Commands>` it may span more than one
 line of input. The prompt for the first line of input is specified by the
-``cmd2.Cmd.prompt`` instance attribute - see
+:attr:`cmd2.Cmd.prompt` instance attribute - see
 :ref:`features/prompt:Customizing the Prompt`. The prompt for subsequent lines
-of input is defined by the ``cmd2.Cmd.continuation_prompt`` attribute.
+of input is defined by the :attr:`cmd2.Cmd.continuation_prompt` attribute.
 
 Use cases
 ---------
diff --git a/docs/features/prompt.rst b/docs/features/prompt.rst
index 244ffb31..49f8d1be 100644
--- a/docs/features/prompt.rst
+++ b/docs/features/prompt.rst
@@ -1,14 +1,40 @@
 Prompt
 ======
 
-``cmd2`` can issue a prompt before soliciting user input.
+``cmd2`` issues a configurable prompt before soliciting user input.
 
 Customizing the Prompt
 ----------------------
 
-This prompt can be configured by setting the `cmd2.Cmd.prompt` instance
+This prompt can be configured by setting the :attr:`cmd2.Cmd.prompt` instance
 attribute. This contains the string which should be printed as a prompt
-for user input.
+for user input.  See the Pirate_ example for the simple use case of statically
+setting the prompt.
+
+.. _Pirate: https://github.com/python-cmd2/cmd2/blob/master/examples/pirate.py#L33
+
+Continuation Prompt
+-------------------
+
+When a user types a
+:ref:`Multiline Command <features/multiline_commands:Multiline Commands>`
+it may span more than one line of input. The prompt for the first line of input
+is specified by the :attr:`cmd2.Cmd.prompt` instance attribute.  The prompt for
+subsequent lines of input is defined by the
+:attr:`cmd2.Cmd.continuation_prompt` attribute.See the Initialization_ example
+for a demonstration of customizing the continuation prompt.
+
+.. _Initialization: https://github.com/python-cmd2/cmd2/blob/master/examples/initialization.py#L33
+
+Updating the prompt
+-------------------
+
+If you wish to update the prompt between commands, you can do so using one of
+the :ref:`Application Lifecycle Hooks <features/hooks:Hooks>` such as a
+:ref:`Postcommand hook <features/hooks:Postcommand Hooks>`.  See
+PythonScripting_ for an example of dynamically updating the prompt.
+
+.. _PythonScripting: https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py#L34-L48
 
 Asynchronous Feedback
 ---------------------
@@ -20,26 +46,19 @@ functionality, the application must be running in a terminal that supports
 VT100 control characters and readline. Linux, Mac, and Windows 10 and greater
 all support these.
 
-async_alert()
-    Used to display an important message to the user while they are at the
-    prompt in between commands. To the user it appears as if an alert message
-    is printed above the prompt and their current input text and cursor
-    location is left alone.
+.. automethod:: cmd2.Cmd.async_alert
+    :noindex:
 
-async_update_prompt()
-    Updates the prompt while the user is still typing at it. This is good for
-    alerting the user to system changes dynamically in between commands. For
-    instance you could alter the color of the prompt to indicate a system
-    status or increase a counter to report an event.
+.. automethod:: cmd2.Cmd.async_update_prompt
+    :noindex:
 
 ``cmd2`` also provides a function to change the title of the terminal window.
 This feature requires the application be running in a terminal that supports
 VT100 control characters. Linux, Mac, and Windows 10 and greater all support
 these.
 
-set_window_title()
-    Sets the terminal window title
-
+.. automethod:: cmd2.Cmd.set_window_title
+    :noindex:
 
 The easiest way to understand these functions is to see the AsyncPrinting_
 example for a demonstration.