Merge branch 'master' into doc_streamline

# Conflicts:
#	docs/features/settings.rst

8 files changed, 30 insertions, 24 deletions

diff --git a/docs/api/utility_classes.rst b/docs/api/utility_classes.rst
index 7ed0c584..2ee92ced 100644
--- a/docs/api/utility_classes.rst
+++ b/docs/api/utility_classes.rst
@@ -1,6 +1,10 @@
 Utility Classes
 ===============
 
+.. autoclass:: cmd2.utils.Settable
+
+    .. automethod:: __init__
+
 .. autoclass:: cmd2.utils.StdSim
 
 .. autoclass:: cmd2.utils.ByteBuf
diff --git a/docs/api/utility_functions.rst b/docs/api/utility_functions.rst
index e2d6f036..4f788e3d 100644
--- a/docs/api/utility_functions.rst
+++ b/docs/api/utility_functions.rst
@@ -23,8 +23,6 @@ Utility Functions
 
 .. autofunction:: cmd2.utils.namedtuple_with_defaults
 
-.. autofunction:: cmd2.utils.cast
-
 .. autofunction:: cmd2.utils.which
 
 .. autofunction:: cmd2.utils.is_text_file
diff --git a/docs/conf.py b/docs/conf.py
index 7a8da9d1..02eb827f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -17,17 +17,11 @@ If extensions (or modules to document with autodoc) are in another directory,
 add these directories to sys.path here. If the directory is relative to the
 documentation root, use os.path.abspath to make it absolute, like shown here.
 """
-import os
-import sys
-
 from pkg_resources import get_distribution
 
 # Import for custom theme from Read the Docs
 import sphinx_rtd_theme
 
-sys.path.insert(0, os.path.abspath('..'))
-
-
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
diff --git a/docs/examples/first_app.rst b/docs/examples/first_app.rst
index 19d573b4..310c8d0c 100644
--- a/docs/examples/first_app.rst
+++ b/docs/examples/first_app.rst
@@ -67,7 +67,7 @@ initializer to our class::
 
         # Make maxrepeats settable at runtime
         self.maxrepeats = 3
-        self.settable['maxrepeats'] = 'max repetitions for speak command'
+        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
 In that initializer, the first thing to do is to make sure we initialize
 ``cmd2``. That's what the ``super().__init__()`` line does. Then we create an
@@ -203,7 +203,7 @@ method so it looks like this::
 
         # Make maxrepeats settable at runtime
         self.maxrepeats = 3
-        self.settable['maxrepeats'] = 'max repetitions for speak command'
+        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
 Shortcuts are passed to the ``cmd2`` initializer, and if you want the built-in
 shortcuts of ``cmd2`` you have to pass them. These shortcuts are defined as a
diff --git a/docs/features/builtin_commands.rst b/docs/features/builtin_commands.rst
index d2cefa71..0db05c96 100644
--- a/docs/features/builtin_commands.rst
+++ b/docs/features/builtin_commands.rst
@@ -93,10 +93,10 @@ within a running application:
 
     (Cmd) set --long
     allow_style: Terminal          # Allow ANSI text style sequences in output (valid values: Terminal, Always, Never)
-    debug: False                   # Show full error stack on error
+    debug: False                   # Show full traceback on exception
     echo: False                    # Echo command issued into output
-    editor: vim                    # Program used by ``edit``
-    feedback_to_output: False      # include nonessentials in `|`, `>` results
+    editor: vim                    # Program used by 'edit'
+    feedback_to_output: False      # include nonessentials in '|', '>' results
     max_completion_items: 50       # Maximum number of CompletionItems to display during tab completion
     quiet: False                   # Don't print nonessential feedback
     timing: False                  # Report execution times
diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst
index 9924caa2..5721caa3 100644
--- a/docs/features/initialization.rst
+++ b/docs/features/initialization.rst
@@ -20,7 +20,7 @@ capabilities which you may wish to utilize while initializing the app::
     """
     import cmd2
     from cmd2 import style
-
+    from cmd2.ansi import FG_COLORS
 
     class BasicApp(cmd2.Cmd):
         CUSTOM_CATEGORY = 'My Custom Commands'
@@ -48,7 +48,10 @@ capabilities which you may wish to utilize while initializing the app::
             self.foreground_color = 'cyan'
 
             # Make echo_fg settable at runtime
-            self.settable['foreground_color'] = 'Foreground color to use with echo command'
+            self.add_settable(cmd2.Settable('foreground_color',
+                                            str,
+                                            'Foreground color to use with echo command',
+                                            choices=FG_COLORS))
 
         @cmd2.with_category(CUSTOM_CATEGORY)
         def do_intro(self, _):
diff --git a/docs/features/plugins.rst b/docs/features/plugins.rst
index caa46b8c..00c0a9f0 100644
--- a/docs/features/plugins.rst
+++ b/docs/features/plugins.rst
@@ -82,10 +82,10 @@ example::
             super().__init__(*args, **kwargs)
             # code placed here runs after cmd2.Cmd initializes
             self.mysetting = 'somevalue'
-            self.settable.update({'mysetting': 'short help message for mysetting'})
+            self.add_settable(cmd2.Settable('mysetting', str, 'short help message for mysetting'))
 
 You can also hide settings from the user by removing them from
-``self.settable``.
+``self.settables``.
 
 Decorators
 ~~~~~~~~~~
diff --git a/docs/features/settings.rst b/docs/features/settings.rst
index cece62b7..e2ce70d6 100644
--- a/docs/features/settings.rst
+++ b/docs/features/settings.rst
@@ -116,15 +116,21 @@ Create New Settings
 -------------------
 
 Your application can define user-settable parameters which your code can
-reference. First create a class attribute with the default value. Then update
-the ``settable`` dictionary with your setting name and a short description
-before you initialize the superclass. Here's an example, from
+reference. In your initialization code:
+
+1. Create an instance attribute with a default value.
+2. Create a :class:`.Settable` object which describes your setting.
+3. Pass the :class:`.Settable` object to
+   :meth:`cmd2.cmd2.Cmd.add_settable`.
+
+Here's an example, from
 ``examples/environment.py``:
 
 .. literalinclude:: ../../examples/environment.py
 
-If you want to be notified when a setting changes (as we do above), then define
-a method ``_onchange_{setting}()``. This method will be called after the user
+If you want to be notified when a setting changes (as we do above), then be
+sure to supply a method to the ``onchange_cb`` parameter of the
+`.cmd2.utils.Settable`. This method will be called after the user
 changes a setting, and will receive both the old value and the new value.
 
 .. code-block:: text
@@ -150,7 +156,7 @@ changes a setting, and will receive both the old value and the new value.
 
 
 Hide Builtin Settings
-----------------------
+---------------------
 
 You may want to prevent a user from modifying a builtin setting. A setting
 must appear in the :attr:`cmd2.Cmd.settable` dictionary in order for it
@@ -160,9 +166,10 @@ Let's say that you never want end users of your program to be able to enable
 full debug tracebacks to print out if an error occurs. You might want to hide
 the :ref:`features/settings:debug` setting. To do so, remove it from the
 :attr:`cmd2.Cmd.settable` dictionary after you initialize your object::
+The :meth:`~.cmd2.Cmd.remove_settable` convenience method makes this easy::
 
   class MyApp(cmd2.Cmd):
 
     def __init__(self):
         super().__init__()
-        self.settable.pop('debug')
+        self.remove_settable('debug')