Add documentation and example for removing built-in commands

For #765

5 files changed, 52 insertions, 10 deletions

diff --git a/docs/examples/index.rst b/docs/examples/index.rst
index 65cb475f..f895059f 100644
--- a/docs/examples/index.rst
+++ b/docs/examples/index.rst
@@ -5,5 +5,5 @@ Examples
    :maxdepth: 1
 
    first_app
-   removing_builtin_commands
+   remove_builtin_commands
    alternate_event_loops
diff --git a/docs/examples/remove_builtin_commands.rst b/docs/examples/remove_builtin_commands.rst
new file mode 100644
index 00000000..c3e73b0c
--- /dev/null
+++ b/docs/examples/remove_builtin_commands.rst
@@ -0,0 +1,41 @@
+Remove Built-in Commands
+=========================
+
+``cmd2`` comes with a bunch of built-in commands. These commands add lots of
+useful functionality, but you might not want them in your application. You can
+either hide these commands, or remove them completely.
+
+
+Hiding Commands
+---------------
+
+When a command is hidden, it is still available to run, but it won't show in
+the help menu. To hide a command::
+
+    class HideBuiltinCommand(cmd2.Cmd):
+        """Hide a built-in command."""
+
+        def __init__(self):
+            super().__init__()
+
+            # To prevent commands from displaying in the help menu
+            # add them to the hidden_commands list
+            self.hidden_commands.append('py')
+
+
+Removing Commands
+-----------------
+
+You can remove a command from your application is defined in ``cmd2.Cmd`` or
+inherited from a :ref:`plugin <features/plugins:Plugins>`. Delete the
+command method in your initialization code::
+
+    class RemoveBuiltinCommand(cmd2.Cmd):
+        """Remove an undesired built-in command."""
+
+        def __init__(self):
+            super().__init__()
+
+            # To remove built-in commands entirely, delete
+            # the "do_*" function from the cmd2.Cmd class
+            del cmd2.Cmd.do_edit
diff --git a/docs/examples/removing_builtin_commands.rst b/docs/examples/removing_builtin_commands.rst
deleted file mode 100644
index 63f5160a..00000000
--- a/docs/examples/removing_builtin_commands.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-Removing Builtin Commands
-=========================
-
-Show how to remove built in comamnds. Say for example you don't like the
-``quit`` command included in ``cmd2``. Your application has to subclass
-``cmd2.Cmd`` to work, which means you inherit the ``quit`` command. Here's how
-to remove it.
diff --git a/docs/features/commands.rst b/docs/features/commands.rst
index 2cdc9851..ab53e990 100644
--- a/docs/features/commands.rst
+++ b/docs/features/commands.rst
@@ -181,3 +181,11 @@ catch it and display it for you. The `debug` :ref:`setting
 `debug` is `false`, which is the default, ``cmd2`` will display the exception
 name and message. If `debug` is `true`, ``cmd2`` will display a traceback, and
 then display the exception name and message.
+
+
+Remove Built-in Commands
+------------------------
+
+See the :ref:`examples/remove_builtin_commands:Remove Built-in Commands`
+example for information on hiding or removing commands included in ``cmd2``
+which you might not want in your application.
diff --git a/examples/remove_unused.py b/examples/remove_builtin_commands.py
index 62103022..4c1794d6 100755
--- a/examples/remove_unused.py
+++ b/examples/remove_builtin_commands.py
@@ -12,7 +12,7 @@ Commands can also be removed entirely by using Python's "del".
 import cmd2
 
 
-class RemoveUnusedBuiltinCommands(cmd2.Cmd):
+class RemoveBuiltinCommands(cmd2.Cmd):
     """ Example cmd2 application where we remove some unused built-in commands."""
 
     def __init__(self):
@@ -27,5 +27,5 @@ class RemoveUnusedBuiltinCommands(cmd2.Cmd):
 
 if __name__ == '__main__':
     import sys
-    app = RemoveUnusedBuiltinCommands()
+    app = RemoveBuiltinCommands()
     sys.exit(app.cmdloop())