Addressed PR comments

Author: tleonhardt

docs/features/argument_processing.md

@@ -34,13 +34,32 @@ All of these decorators accept an optional **preserve_quotes** argument which de
 Setting this argument to `True` is useful for cases where you are passing the arguments to another
 command which might have its own argument parsing.
 
+## with_argparser decorator
+
+The [@with_argparser][cmd2.with_argparser] decorator can accept the following for its first
+argument:
+
+1. An existing instance of `argparse.ArgumentParser`
+2. A function or static method which returns an instance of `argparse.ArgumentParser`
+3. Cmd or CommandSet class method which returns an instance of `argparse.ArgumentParser`
+
+In all cases the `@with_argparser` decorator creates a deep copy of the parser instance which it
+stores internally. A consequence is that parsers don't need to be unique across commands.
+
+!!! warning
+
+    Since the `@with_argparser` decorator is making a deep-copy of the parser provided, if you wish
+    to dynamically modify this parser at a later time, you need to retrieve this deep copy. This can
+    be done using `self._command_parsers.get(self.do_commandname)`.
+
 ## Argument Parsing
 
-For each command in the `cmd2.Cmd` subclass which requires argument parsing, create a unique
-instance of `argparse.ArgumentParser()` which can parse the input appropriately for the command.
-Then decorate the command method with the `@with_argparser` decorator, passing the argument parser
-as the first parameter to the decorator. This changes the second argument of the command method,
-which will contain the results of `ArgumentParser.parse_args()`.
+For each command in the `cmd2.Cmd` subclass which requires argument parsing, create an instance of
+`argparse.ArgumentParser()` which can parse the input appropriately for the command (or provide a
+function/method that returns such a parser). Then decorate the command method with the
+`@with_argparser` decorator, passing the argument parser as the first parameter to the decorator.
+This changes the second argument of the command method, which will contain the results of
+`ArgumentParser.parse_args()`.
 
 Here's what it looks like:
 
@@ -82,9 +101,9 @@ to set the description for the `argparse.ArgumentParser`.
 
 !!! tip "description and epilog fields are rich objects"
 
-    While the `help` text itself is simply a string, both the `description` and `epilog` can contain
-    [rich](https://github.com/Textualize/rich) objects. For the `description` and `epilog` fields, you can pass
-    in any `rich` object, including Text, Tables, Markdown.
+    While the `help` field is simply a string, both the `description` and `epilog` fields can accept any
+    [rich](https://github.com/Textualize/rich) renderable. This allows you to include all of rich's
+    built-in objects like `Text`, `Table`, and `Markdown`.
 
 With this code:
 

docs/features/disable_commands.md

@@ -11,7 +11,7 @@ See
 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.
+example of dynamically enabling and disabling custom commands at runtime.
 
 ## Remove A Command
 

docs/features/generating_output.md

@@ -19,10 +19,31 @@ output you generate must be sent to `self.stdout`. You can use the methods descr
 everything will work fine. [cmd2.Cmd][] also includes a number of output related methods which you
 may use to enhance the output your application produces.
 
-Since `cmd2` has a dependency on the [rich](https://github.com/Textualize/rich) library, all of
-`cmd2`'s output methods can natively render `rich`
+Since `cmd2` has a dependency on the [rich](https://github.com/Textualize/rich) library, the
+following [cmd2.Cmd][] output methods can natively render `rich`
 [renderable objects](https://rich.readthedocs.io/en/latest/protocol.html), enabling beautiful and
-complex output.
+complex output:
+
+- [poutput][cmd2.Cmd.poutput]
+- [perror][cmd2.Cmd.perror]
+- [psuccess][cmd2.Cmd.psuccess]
+- [pwarning][cmd2.Cmd.pwarning]
+- [pfeedback][cmd2.Cmd.pfeedback]
+- [ppaged][cmd2.Cmd.ppaged]
+
+!!! tip "Advanced output customization"
+
+      Each of the above methods accepts additional optional parameters that help control how the output is
+      formatted:
+
+      - `sep`: string to write between printed text. Defaults to " "
+      - `end`: string to write at end of printed text. Defaults to a newline
+      - `style`: optional style to apply to output
+      - `soft_wrap`: Enable soft wrap mode. If True, lines of text will not be word-wrapped or cropped to fit the terminal width. Defaults to True
+      - `emoji`: If True, Rich will replace emoji codes (e.g., 😃) with their corresponding Unicode characters. Defaults to False
+      - `markup`: If True, Rich will interpret strings with tags (e.g., [bold]hello[/bold]) as styled output. Defaults to False
+      - `highlight`: If True, Rich will automatically apply highlighting to elements within strings, such as common Python data types like numbers, booleans, or None.
+      - `rich_print_kwargs`: optional additional keyword arguments to pass to Rich's `Console.print()`
 
 ## Ordinary Output
 
@@ -140,6 +161,11 @@ with display widths greater than 1. Additionally, ANSI style sequences are safel
 count toward the display width. This means colored text is supported. If text has line breaks, then
 each line is aligned independently.
 
+!!! tip "Advanced alignment customization"
+
+      You can also control output alignment using the `rich_print_kwargs.justify` member when calling
+      `cmd2`'s print methods.
+
 ## Columnar Output
 
 When generating output in multiple columns, you often need to calculate the width of each item so

docs/features/scripting.md

@@ -112,8 +112,9 @@ script for more information.
 If your cmd2 application follows the
 [Unix design philosophy](https://en.wikipedia.org/wiki/Unix_philosophy) a scripter will have the
 most flexibility to create workflows using different commands. If the designer's application is more
-complete and less likely to be augmented in the future a scripter can use simple serial scripts with
-little control flow. In either case, choices made by the designer will have effects on scripters.
+complete and less likely to be augmented in the future, a scripter can use simple serial scripts
+with little control flow. In either case, choices made by the designer will have effects on
+scripters.
 
 The following diagram illustrates the different boundaries to keep in mind.
 

docs/features/shortcuts_aliases_macros.md

@@ -29,7 +29,7 @@ class App(Cmd):
 
     This warning applies in general to many other attributes which are not settable at runtime.
 
-!!! tip
+!!! note
 
     Command, alias, and macro names cannot start with a shortcut
 
@@ -62,7 +62,9 @@ Use `alias delete` to remove aliases
 
 For more details run: `help alias delete`
 
-Note: Aliases cannot have the same name as a command or macro
+!!! note
+
+    Aliases cannot have the same name as a command or macro
 
 ## Macros
 
@@ -99,6 +101,6 @@ For more details on listing macros run: `help macro list`
 
 For more details on deleting macros run: `help macro delete`
 
-!!! warning
+!!! note
 
     Macros cannot have the same name as a command or alias

docs/features/theme.md

@@ -1,7 +1,7 @@
 # Theme
 
 `cmd2` provides the ability to configure an overall theme for your application using the
-[cmd2.rich_utils.set_theme][] function. This is based o the
+[cmd2.rich_utils.set_theme][] function. This is based on the
 [rich.theme](https://rich.readthedocs.io/en/stable/reference/theme.html) container for style
 information. You can use this to brand your application and set an overall consistent look and feel
 that is appealing to your user base.

docs/migrating/minimum.md

@@ -43,6 +43,6 @@ application, you may be able to remove them. See [Exiting](../features/misc.md#e
 If you are distributing your application, you'll also need to ensure that `cmd2` is properly
 installed. You will need to add the following dependency to your `pyproject.toml` or `setup.py`:
 
-    'cmd2>=2.7'
+    'cmd2>=3,<4'
 
 See [Integrate cmd2 Into Your Project](../overview/integrating.md) for more details.

docs/overview/integrating.md

@@ -3,7 +3,7 @@
 Once installed, you will want to ensure that your project's dependencies include `cmd2`. Make sure
 your `pyproject.toml` or `setup.py` includes the following dependency
 
-    'cmd2>=2.7'
+    'cmd2>=3,<4'
 
 The `cmd2` project uses :simple-semver: [Semantic Versioning](https://semver.org), which means that
 any incompatible API changes will be release with a new major version number. The public API is