Documentation updates

Author: kotfu

CHANGELOG.md

@@ -1,4 +1,4 @@
-## 0.9.26 (TBD, 2020)
+## 1.0.0-rc1 (TBD, 2020)
 * Enhancements
     * Changed the default help text to make `help -v` more discoverable
     * Added `add_settable()` and `remove_settable()` convenience methods to update `self.settable` dictionary
@@ -10,9 +10,11 @@
         * `prompt`
     * `self.settable` changed to `self.settables`
         * It is now a Dict[str, Settable] instead of Dict[str, str]
+        * setting onchange callbacks have a new method signature and must be added to the
+          Settable instance in order to be called
         * **set** command now supports tab-completion of values
     * Removed `cast()` utility function
-    
+
 ## 0.9.25 (January 26, 2020)
 * Enhancements
     * Reduced what gets put in package downloadable from PyPI (removed irrelevant CI config files and such)
@@ -74,7 +76,7 @@
     * Fix bug where cmd2 ran 'stty sane' command when stdin was not a terminal
 * Enhancements
     * Send all startup script paths to run_script. Previously we didn't do this if the file was empty, but that
-    showed no record of the run_script command in history. 
+    showed no record of the run_script command in history.
     * Made it easier for developers to override `edit` command by having `do_history` no longer call `do_edit`. This
     also removes the need to exclude `edit` command from history list.
     * It is no longer necessary to set the `prog` attribute of an argparser with subcommands. cmd2 now automatically
@@ -143,7 +145,7 @@
 * Enhancements
     * Greatly simplified using argparse-based tab completion. The new interface is a complete overhaul that breaks
     the previous way of specifying completion and choices functions. See header of [argparse_custom.py](https://github.com/python-cmd2/cmd2/blob/master/cmd2/argparse_custom.py)
-    for more information. 
+    for more information.
     * Enabled tab completion on multiline commands
 * **Renamed Commands Notice**
     * The following commands were renamed in the last release and have been removed in this release
@@ -153,7 +155,7 @@
     * We apologize for any inconvenience, but the new names are more self-descriptive
         * Lots of end users were confused particularly about what exactly `load` should be loading
 * Breaking Changes
-    * Restored `cmd2.Cmd.statement_parser` to be a public attribute (no underscore) 
+    * Restored `cmd2.Cmd.statement_parser` to be a public attribute (no underscore)
         * Since it can be useful for creating [post-parsing hooks](https://cmd2.readthedocs.io/en/latest/features/hooks.html#postparsing-hooks)
     * Completely overhauled the interface for adding tab completion to argparse arguments. See enhancements for more details.
     * `ACArgumentParser` is now called `Cmd2ArgumentParser`
@@ -193,7 +195,7 @@
         * `perror` - print a message to sys.stderr
         * `pexcept` - print Exception message to sys.stderr. If debug is true, print exception traceback if one exists
     * Signature of `poutput` and `perror` significantly changed
-        * Removed color parameters `color`, `err_color`, and `war_color` from `poutput` and `perror` 
+        * Removed color parameters `color`, `err_color`, and `war_color` from `poutput` and `perror`
             * See the docstrings of these methods or the [cmd2 docs](https://cmd2.readthedocs.io/en/latest/features/generating_output.html) for more info on applying styles to output messages
         * `end` argument is now keyword-only and cannot be specified positionally
         * `traceback_war` no longer exists as an argument since it isn't needed now that `perror` and `pexcept` exist
@@ -203,7 +205,7 @@
         * `COLORS_NEVER` --> `ANSI_NEVER`
         * `COLORS_TERMINAL` --> `ANSI_TERMINAL`
 * **Renamed Commands Notice**
-    * The following commands have been renamed. The old names will be supported until the next release. 
+    * The following commands have been renamed. The old names will be supported until the next release.
         * `load` --> `run_script`
         * `_relative_load` --> `_relative_run_script`
         * `pyscript` --> `run_pyscript`
@@ -222,7 +224,7 @@
     * Fixed issue where `_cmdloop()` suppressed exceptions by returning from within its `finally` code
     * Fixed UnsupportedOperation on fileno error when a shell command was one of the commands run while generating
     a transcript
-    * Fixed bug where history was displaying expanded multiline commands when -x was not specified 
+    * Fixed bug where history was displaying expanded multiline commands when -x was not specified
 * Enhancements
     * **Added capability to chain pipe commands and redirect their output (e.g. !ls -l | grep user | wc -l > out.txt)**
     * `pyscript` limits a command's stdout capture to the same period that redirection does.
@@ -243,7 +245,7 @@
     * Text scripts now run immediately instead of adding their commands to `cmdqueue`. This allows easy capture of
     the entire script's output.
     * Added member to `CommandResult` called `stop` which is the return value of `onecmd_plus_hooks` after it runs
-    the given command line. 
+    the given command line.
 * Breaking changes
     * Replaced `unquote_redirection_tokens()` with `unquote_specific_tokens()`. This was to support the fix
     that allows terminators in alias and macro values.

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

docs/conf.py

@@ -25,9 +25,6 @@
 # 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.

docs/features/settings.rst

@@ -3,8 +3,8 @@ Settings
 
 Settings provide a mechanism for a user to control the behavior of a ``cmd2``
 based application. A setting is stored in an instance attribute on your
-subclass of :class:`cmd2.cmd2.Cmd` and must also appear in the
-:attr:`cmd2.cmd2.Cmd.settable` dictionary. Developers may set default values
+subclass of :class:`.cmd2.Cmd` and must also appear in the
+:attr:`~.cmd2.Cmd.settable` dictionary. Developers may set default values
 for these settings and users can modify them at runtime using the
 :ref:`features/builtin_commands:set` command. Developers can
 :ref:`features/settings:Create New Settings` and can also
@@ -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
@@ -153,13 +159,14 @@ Hide Builtin Settings
 ---------------------
 
 You may want to prevent a user from modifying a builtin setting. A setting
-must appear in the :attr:`cmd2.cmd2.Cmd.settable` dictionary in order for it
+must appear in the :attr:`~.cmd2.Cmd.settable` dictionary in order for it
 to be available to the :ref:`features/builtin_commands:set` command.
 
 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.cmd2.Cmd.settable` dictionary after you initialize your object::
+: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):
 

examples/environment.py

@@ -8,12 +8,16 @@
 
 class EnvironmentApp(cmd2.Cmd):
     """ Example cmd2 application. """
-    degrees_c = 22
-    sunny = False
 
     def __init__(self):
         super().__init__()
-        self.add_settable(cmd2.Settable('degrees_c', int, 'Temperature in Celsius'))
+        self.degrees_c = 22
+        self.sunny = False
+        self.add_settable(cmd2.Settable('degrees_c',
+                                        int,
+                                        'Temperature in Celsius',
+                                        onchange_cb=self._onchange_degrees_c
+                                        ))
         self.add_settable(cmd2.Settable('sunny', bool, 'Is it sunny outside?'))
 
     def do_sunbathe(self, arg):