Add documentation and example for removing built-in commands

For #765

Author: kotfu

docs/examples/index.rst

@@ -5,5 +5,5 @@ Examples
    :maxdepth: 1
 
    first_app
-   removing_builtin_commands
+   remove_builtin_commands
    alternate_event_loops

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

docs/examples/removing_builtin_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.

docs/features/commands.rst

@@ -12,7 +12,7 @@
 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 @@ def __init__(self):
 
 if __name__ == '__main__':
     import sys
-    app = RemoveUnusedBuiltinCommands()
+    app = RemoveBuiltinCommands()
     sys.exit(app.cmdloop())