Revisions and improvements for hooks and plugins

1 files changed, 27 insertions, 29 deletions

diff --git a/docs/features/plugins.rst b/docs/features/plugins.rst
index d6e3eb9c..ecd3a32d 100644
--- a/docs/features/plugins.rst
+++ b/docs/features/plugins.rst
@@ -5,18 +5,15 @@ Plugins
 a ``cmd2`` plugin which can extend basic ``cmd2`` functionality and can be
 used by multiple applications.
 
-Adding functionality
---------------------
-
 There are many ways to add functionality to ``cmd2`` using a plugin. Most
 plugins will be implemented as a mixin. A mixin is a class that encapsulates
 and injects code into another class. Developers who use a plugin in their
-``cmd2`` project, will inject the plugin's code into their subclass of
-``cmd2.Cmd``.
+``cmd2`` project will inject the plugin's code into their subclass of
+:class:`cmd2.Cmd`.
 
 
 Mixin and Initialization
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 The following short example shows how to mix in a plugin and how the plugin
 gets initialized.
@@ -29,7 +26,6 @@ Here's the plugin::
             super().__init__(*args, **kwargs)
             # code placed here runs after cmd2.Cmd initializes
 
-
 and an example app which uses the plugin::
 
     import cmd2
@@ -44,23 +40,24 @@ and an example app which uses the plugin::
             # code placed here runs after cmd2.Cmd and
             # all plugins have initialized
 
-Note how the plugin must be inherited (or mixed in) before ``cmd2.Cmd``.
+Note how the plugin must be inherited (or mixed in) before :class:`cmd2.Cmd`.
 This is required for two reasons:
 
-- The ``cmd.Cmd.__init__()`` method in the python standard library does not
+- The ``cmd.Cmd.__init__`` method in the python standard library does not
   call ``super().__init__()``. Because of this oversight, if you don't
   inherit from ``MyPlugin`` first, the ``MyPlugin.__init__()`` method will
   never be called.
-- You may want your plugin to be able to override methods from ``cmd2.Cmd``.
-  If you mixin the plugin after ``cmd2.Cmd``, the python method resolution
-  order will call ``cmd2.Cmd`` methods before it calls those in your plugin.
+- You may want your plugin to be able to override methods from
+  :class:`cmd2.Cmd`. If you mixin the plugin after ``cmd2.Cmd``, the python
+  method resolution order will call :class:`cmd2.Cmd` methods before it calls
+  those in your plugin.
 
 
 Add commands
-~~~~~~~~~~~~
+------------
 
 Your plugin can add user visible commands. You do it the same way in a plugin
-that you would in a ``cmd2.Cmd`` app::
+that you would in a :class:`cmd2.Cmd` app::
 
     class MyPlugin:
         def do_say(self, statement):
@@ -68,12 +65,12 @@ that you would in a ``cmd2.Cmd`` app::
             self.poutput(statement)
 
 You have all the same capabilities within the plugin that you do inside a
-``cmd2.Cmd`` app, including argument parsing via decorators and custom help
-methods.
+:class:`cmd2.Cmd` app, including argument parsing via decorators and custom
+help methods.
 
 
 Add (or hide) settings
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 A plugin may add user controllable settings to the application. Here's an
 example::
@@ -86,33 +83,34 @@ example::
             self.mysetting = 'somevalue'
             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.settables``.
+You can hide settings from the user by calling
+:meth:`~cmd2.Cmd.remove_settable`. See :ref:`features/settings:Settings` for
+more information.
 
 
 Decorators
-~~~~~~~~~~
+----------
 
 Your plugin can provide a decorator which users of your plugin can use to
 wrap functionality around their own commands.
 
 
 Override methods
-~~~~~~~~~~~~~~~~
+----------------
 
-Your plugin can override core ``cmd2.Cmd`` methods, changing their behavior.
-This approach should be used sparingly, because it is very brittle. If a
-developer chooses to use multiple plugins in their application, and several
-of the plugins override the same method, only the first plugin to be mixed in
-will have the overridden method called.
+Your plugin can override core :class:`cmd2.Cmd` methods, changing their
+behavior. This approach should be used sparingly, because it is very brittle.
+If a developer chooses to use multiple plugins in their application, and
+several of the plugins override the same method, only the first plugin to be
+mixed in will have the overridden method called.
 
 Hooks are a much better approach.
 
 
 Hooks
-~~~~~
+-----
 
-Plugins can register hook methods, which are called by :class:`~cmd2.Cmd`
+Plugins can register hook methods, which are called by :class:`cmd2.Cmd`
 during various points in the application and command processing lifecycle.
 Plugins should not override any of the deprecated hook methods, instead they
 should register their hooks as described in the :ref:`features/hooks:Hooks`
@@ -147,7 +145,7 @@ ways hooks can influence the lifecycle.
 
 
 Classes and Functions
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 Your plugin can also provide classes and functions which can be used by
 developers of ``cmd2`` based applications. Describe these classes and