More documentation updates

Author: tleonhardt

docs/features/builtin_commands.md

@@ -35,7 +35,7 @@ history. See [History](history.md) for more information.
 
 ### ipy (optional)
 
-This optional opt-in command enters an interactive IPython shell. See
+This optional opt-in command enters an interactive :simple-jupyter: IPython shell. See
 [IPython (optional)](./embedded_python_shells.md#ipython-optional) for more information.
 
 ### macro

docs/features/completion.md

@@ -78,8 +78,8 @@ user. These include the following example cases:
 - A previous command line argument that determines the data set being completed is invalid
 - Tab completion hints
 
-`cmd2` provides the `cmd2.exceptions.CompletionError` exception class for this capability. If an
-error occurs in which it is more desirable to display a message than a stack trace, then raise a
+`cmd2` provides the [CompletionError][cmd2.CompletionError] exception class for this capability. If
+an error occurs in which it is more desirable to display a message than a stack trace, then raise a
 `CompletionError`. By default, the message displays in red like an error. However, `CompletionError`
 has a member called `apply_style`. Set this False if the error style should not be applied. For
 instance, `ArgparseCompleter` sets it to False when displaying completion hints.
@@ -90,7 +90,7 @@ When using `cmd2`'s [@with_argparser][cmd2.with_argparser] decorator, `cmd2` pro
 completion of flag names.
 
 Tab completion of argument values can be configured by using one of three parameters to
-`argparse.ArgumentParser.add_argument`
+[argparse.ArgumentParser.add_argument](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_argument)
 
 - `choices`
 - `choices_provider`
@@ -105,17 +105,17 @@ example for a demonstration of how to use the `choices_provider` parameter. See
 [argparse_completion](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_completion.py)
 example for a demonstration of how to use the `completer` parameter.
 
-When tab completing flags or argument values for a `cmd2` command using one of these decorators,
-`cmd2` keeps track of state so that once a flag has already previously been provided, it won't
-attempt to tab complete it again. When no completion results exist, a hint for the current argument
-will be displayed to help the user.
+When tab completing flags or argument values for a `cmd2` command using the `@with_argparser`
+decorator, `cmd2` keeps track of state so that once a flag has already previously been provided, it
+won't attempt to tab complete it again. When no completion results exist, a hint for the current
+argument will be displayed to help the user.
 
 ## CompletionItem For Providing Extra Context
 
 When tab completing things like a unique ID from a database, it can often be beneficial to provide
 the user with some extra context about the item being completed, such as a description. To
-facilitate this, `cmd2` defines the `cmd2.CompletionItem` class which can be returned from any of
-the 3 completion parameters: `choices`, `choices_provider`, and `completer`.
+facilitate this, `cmd2` defines the [CompletionItem][cmd2.CompletionItem] class which can be
+returned from any of the 3 completion parameters: `choices`, `choices_provider`, and `completer`.
 
 See the
 [argparse_completion](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_completion.py)
@@ -124,8 +124,8 @@ demonstration of how this is used.
 
 ## Custom Completion with `read_input()`
 
-`cmd2` provides `cmd2.Cmd.read_input` as an alternative to Python's `input()` function. `read_input`
-supports configurable tab completion and up-arrow history at the prompt. See
+`cmd2` provides [cmd2.Cmd.read_input][] as an alternative to Python's `input()` function.
+`read_input` supports configurable tab completion and up-arrow history at the prompt. See
 [read_input](https://github.com/python-cmd2/cmd2/blob/main/examples/read_input.py) example for a
 demonstration.
 

docs/features/disable_commands.md

@@ -2,14 +2,21 @@
 
 `cmd2` allows a developer to:
 
-- remove commands included in `cmd2`
-- prevent commands from appearing in the help menu (hide commands)
-- disable and re-enable commands at runtime
+- Remove commands included in `cmd2`
+- Prevent commands from appearing in the help menu (hide commands)
+- Disable and re-enable commands at runtime
+
+See
+[remove_builtin_commands.py](https://github.com/python-cmd2/cmd2/blob/main/examples/remove_builtin_commands.py)
+for and example of removing or hiding built-in commands.
+
+See [command_sets.py](https://github.com/python-cmd2/cmd2/blob/main/examples/command_sets.py) for an
+example of dynamically enabling and dis-abling custom commands at runtime.
 
 ## Remove A Command
 
 When a command has been removed, the command method has been deleted from the object. The command
-doesn't show up in help, and it can't be executed. This approach is appropriate if you never want a
+doesn't show up in help and it can't be executed. This approach is appropriate if you never want a
 built-in command to be part of your application. Delete the command method in your initialization
 code:
 
@@ -26,9 +33,9 @@ code:
 
 ## Hide A Command
 
-When a command is hidden, it won't show up in the help menu, but if the user knows it's there and
-types the command, it will be executed. You hide a command by adding it to the `hidden_commands`
-list:
+When a command is hidden, it won't show up in the help menu and it won't tab-complete, but if the
+user knows it's there and types the command, it will be executed. You hide a command by adding it to
+the `hidden_commands` list:
 
 ```py
 class HiddenCommands(cmd2.Cmd):
@@ -101,3 +108,6 @@ Similarly, you can re-enable all the commands in a category:
 ```py
 self.enable_category('Server Information')
 ```
+
+See [help_categories.py](https://github.com/python-cmd2/cmd2/blob/main/examples/help_categories.py)
+for an example of enabling and disabling and entire category of commands dynamically at runtime.

docs/features/embedded_python_shells.md

@@ -2,8 +2,8 @@
 
 ## Python (optional)
 
-If the `cmd2.Cmd` class is instantiated with `include_py=True`, then the optional `py` command will
-be present and run an interactive Python shell:
+If the [cmd2.Cmd][] class is instantiated with `include_py=True`, then the optional `py` command
+will be present and run an interactive Python shell:
 
 ```py
 from cmd2 import Cmd
@@ -33,10 +33,12 @@ All of these parameters are also available to Python scripts which run in your a
 - has the ability to pass command-line arguments to the scripts invoked
 
 This command provides a more complex and powerful scripting capability than that provided by the
-simple text file scripts. Python scripts can include conditional control flow logic. See the
-**python_scripting.py** `cmd2` application and the **script_conditional.py** script in the
-`examples` source code directory for an example of how to achieve this in your own applications. See
-[Scripting](./scripting.md) for an explanation of both scripting methods in **cmd2** applications.
+simple text file scripts. Python scripts can include conditional control flow logic. See
+[python_scripting.py](https://github.com/python-cmd2/cmd2/blob/main/examples/python_scripting.py)
+`cmd2` and the
+[conditional.py](https://github.com/python-cmd2/cmd2/blob/main/examples/scripts/conditional.py)
+script for an example of how to achieve this in your own applications. See
+[Scripting](./scripting.md) for an explanation of both scripting methods in `cmd2` applications.
 
 A simple example of using `run_pyscript` is shown below along with the
 [arg_printer](https://github.com/python-cmd2/cmd2/blob/main/examples/scripts/arg_printer.py) script:

docs/features/generating_output.md

@@ -26,16 +26,17 @@ complex output.
 
 ## Ordinary Output
 
-The `cmd2.Cmd.poutput` method is similar to the Python
-[built-in print function](https://docs.python.org/3/library/functions.html#print).
-`cmd2.Cmd.poutput` adds two conveniences:
+The [poutput][cmd2.Cmd.poutput] method is similar to the Python built-in
+[print](https://docs.python.org/3/library/functions.html#print) function. `poutput` adds a few
+conveniences:
 
 1. Since users can pipe output to a shell command, it catches `BrokenPipeError` and outputs the
    contents of `self.broken_pipe_warning` to `stderr`. `self.broken_pipe_warning` defaults to an
    empty string so this method will just swallow the exception. If you want to show an error
    message, put it in `self.broken_pipe_warning` when you initialize `cmd2.Cmd`.
 2. It examines and honors the [allow_style](./settings.md#allow_style) setting. See
    [Colored Output](#colored-output) below for more details.
+3. It allows printing arbitrary `rich` renderable objects which can get visually quite complex.
 
 Here's a simple command that shows this method in action:
 
@@ -48,20 +49,22 @@ def do_echo(self, args):
 ## Error Messages
 
 When an error occurs in your program, you can display it on `sys.stderr` by calling the
-`.cmd2.Cmd.perror` method. By default this method applies `Cmd2Style.ERROR` to the output.
+[perror][cmd2.Cmd.perror] method. By default this method applies
+[Cmd2Style.ERROR][cmd2.Cmd2Style.ERROR] to the output.
 
 ## Warning Messages
 
-`cmd2.Cmd.pwarning` is just like `cmd2.Cmd.perror` but applies `Cmd2Style.WARNING` to the output.
+[pwarning][cmd2.Cmd.pwarning] is just like `cmd2.Cmd.perror` but applies `Cmd2Style.WARNING` to the
+output.
 
 ## Feedback
 
 You may have the need to display information to the user which is not intended to be part of the
 generated output. This could be debugging information or status information about the progress of
 long running commands. It's not output, it's not error messages, it's feedback. If you use the
 [Timing](./settings.md#timing) setting, the output of how long it took the command to run will be
-output as feedback. You can use the `cmd2.Cmd.pfeedback` method to produce this type of output, and
-several [Settings](./settings.md) control how it is handled.
+output as feedback. You can use the [pfeedback][cmd2.Cmd.pfeedback] method to produce this type of
+output, and several [Settings](./settings.md) control how it is handled.
 
 If the [quiet](./settings.md#quiet) setting is `True`, then calling `cmd2.Cmd.pfeedback` produces no
 output. If [quiet](./settings.md#quiet) is `False`, the
@@ -71,17 +74,19 @@ send the output to `stdout` or `stderr`.
 ## Exceptions
 
 If your app catches an exception and you would like to display the exception to the user, the
-`cmd2.Cmd.pexcept` method can help. The default behavior is to just display the message contained
-within the exception. However, if the [debug](./settings.md#debug) setting is `True`, then the
-entire stack trace will be displayed.
+[pexcept][cmd2.Cmd.pexcept] method can help. The default behavior is to just display the message
+contained within the exception. However, if the [debug](./settings.md#debug) setting is `True`, then
+the entire stack trace will be displayed.
 
 ## Paging Output
 
 If you know you are going to generate a lot of output, you may want to display it in a way that the
 user can scroll forwards and backwards through it. If you pass all of the output to be displayed in
-a single call to `.cmd2.Cmd.ppaged`, it will be piped to an operating system appropriate shell
-command to page the output. On Windows, the output is piped to `more`; on Unix-like operating
-systems like MacOS and Linux, it is piped to `less`.
+a single call to [ppaged][cmd2.Cmd.ppaged], it will be piped to an operating system appropriate
+shell command to page the output. On Windows, the output is piped to
+[more](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/more); on
+Unix-like operating systems like MacOS and Linux, it is piped to
+[less](https://man7.org/linux/man-pages/man1/less.1.html).
 
 ## Colored Output
 
@@ -102,20 +107,21 @@ all colors available to your `cmd2` application.
 
 ### Custom Themes
 
-`cmd2` uses a `rich` `Theme` object to define styles for various UI elements. You can define your
-own custom theme using `cmd2.rich_utils.set_theme`. See the
+`cmd2` uses a `rich` [Theme](https://rich.readthedocs.io/en/stable/reference/theme.html) object to
+define styles for various UI elements. You can define your own custom theme using
+[cmd2.rich_utils.set_theme][]. See the
 [rich_theme.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_theme.py) example for
 more information.
 
 After adding the desired escape sequences to your output, you should use one of these methods to
 present the output to the user:
 
-- `cmd2.Cmd.poutput`
-- `cmd2.Cmd.perror`
-- `cmd2.Cmd.pwarning`
-- `cmd2.Cmd.pexcept`
-- `cmd2.Cmd.pfeedback`
-- `cmd2.Cmd.ppaged`
+- [cmd2.Cmd.poutput][]
+- [cmd2.Cmd.perror][]
+- [cmd2.Cmd.pwarning][]
+- [cmd2.Cmd.pexcept][]
+- [cmd2.Cmd.pfeedback][]
+- [cmd2.Cmd.ppaged][]
 
 These methods all honor the [allow_style](./settings.md#allow_style) setting, which users can modify
 to control whether these escape codes are passed through to the terminal or not.
@@ -125,9 +131,9 @@ to control whether these escape codes are passed through to the terminal or not.
 If you would like to generate output which is left, center, or right aligned within a specified
 width or the terminal width, the following functions can help:
 
-- `cmd2.string_utils.align_left`
-- `cmd2.string_utils.align_center`
-- `cmd2.string_utils.align_right`
+- [cmd2.string_utils.align_left][]
+- [cmd2.string_utils.align_center][]
+- [cmd2.string_utils.align_right][]
 
 These functions differ from Python's string justifying functions in that they support characters
 with display widths greater than 1. Additionally, ANSI style sequences are safely ignored and do not
@@ -141,6 +147,6 @@ you can pad it appropriately with spaces. However, there are categories of Unico
 occupy 2 cells, and other that occupy 0. To further complicate matters, you might have included ANSI
 escape sequences in the output to generate colors on the terminal.
 
-The `cmd2.string_utils.str_width` function solves both of these problems. Pass it a string, and
+The [cmd2.string_utils.str_width][] function solves both of these problems. Pass it a string, and
 regardless of which Unicode characters and ANSI text style escape sequences it contains, it will
 tell you how many characters on the screen that string will consume when printed.

examples/remove_builtin_commands.py

@@ -18,7 +18,7 @@ def __init__(self) -> None:
         super().__init__()
 
         # To hide commands from displaying in the help menu, add them to the hidden_commands list
-        self.hidden_commands.append('py')
+        self.hidden_commands.append('history')
 
         # To remove built-in commands entirely, delete their "do_*" function from the cmd2.Cmd class
         del cmd2.Cmd.do_edit