[rich_utils] added Paragraph Help Formatters based on rich_argparse classes

Author: neoniobium

cmd2/__init__.py

@@ -47,7 +47,9 @@
 from .rich_utils import (
     ArgumentDefaultsCmd2HelpFormatter,
     Cmd2HelpFormatter,
+    ExtendedParagraphCmd2HelpFormatter,
     MetavarTypeCmd2HelpFormatter,
+    ParagraphCmd2HelpFormatter,
     RawDescriptionCmd2HelpFormatter,
     RawTextCmd2HelpFormatter,
     TextGroup,
@@ -101,7 +103,9 @@
     "ArgumentDefaultsCmd2HelpFormatter",
     "Cmd2HelpFormatter",
     "get_theme",
+    "ExtendedParagraphCmd2HelpFormatter",
     "MetavarTypeCmd2HelpFormatter",
+    "ParagraphCmd2HelpFormatter",
     "RawDescriptionCmd2HelpFormatter",
     "RawTextCmd2HelpFormatter",
     "set_theme",

cmd2/rich_utils.py

@@ -44,6 +44,7 @@
     RawTextRichHelpFormatter,
     RichHelpFormatter,
 )
+from rich_argparse.contrib import ExtendedParagraphRichHelpFormatter, ParagraphRichHelpFormatter
 
 from . import constants
 from .styles import (
@@ -269,6 +270,24 @@ class MetavarTypeCmd2HelpFormatter(
     """  # noqa: D205
 
 
+class ParagraphCmd2HelpFormatter(
+    ParagraphRichHelpFormatter,
+    Cmd2HelpFormatter,
+):
+    r"""Rich help message formatter which retains paragraph separation with spacing
+    using `\\n\\n`.
+    """  # noqa: D205
+
+
+class ExtendedParagraphCmd2HelpFormatter(
+    ExtendedParagraphRichHelpFormatter,
+    Cmd2HelpFormatter,
+):
+    r"""Cmd2 help message formatter which retains paragraph separation without
+    spacing using `\\n\\n` and paragraph spacing using `\\n\\n\\n`.
+    """  # noqa: D205
+
+
 class TextGroup:
     """A block of text which is formatted like an argparse argument group, including a title.
 

docs/features/argument_processing.md

@@ -206,7 +206,7 @@ This command cannot generate tags with no content, like <br/>
 
 ### Argparse HelpFormatter classes
 
-`cmd2` has 5 different Argparse HelpFormatter classes, all of which are based on the
+`cmd2` has 7 different Argparse HelpFormatter classes, all of which are based on the
 `RichHelpFormatter` class from [rich-argparse](https://github.com/hamdanal/rich-argparse). The
 benefit is that your `cmd2` applications now have more aesthetically pleasing help which includes
 color to make it quicker and easier to visually parse help text. This works for all supported
@@ -215,8 +215,12 @@ versions of Python.
 - [Cmd2HelpFormatter][cmd2.argparse_utils.Cmd2HelpFormatter] - default help formatter class
 - [ArgumentDefaultsCmd2HelpFormatter][cmd2.argparse_utils.ArgumentDefaultsCmd2HelpFormatter] - adds
   default values to argument help
+- [ParagraphCmd2HelpFormatter][cmd2.argparse_utils.ParagraphCmd2HelpFormatter] - retains paragraph
+  separation with spacing using `\\n\\n`
 - [MetavarTypeCmd2HelpFormatter][cmd2.argparse_utils.MetavarTypeCmd2HelpFormatter] - uses the
   argument 'type' as the default metavar value (instead of the argument 'dest')
+- [ExtendedParagraphCmd2HelpFormatter][cmd2.argparse_utils.ExtendedParagraphCmd2HelpFormatter] - retains
+  paragraph separation without spacing using `\\n\\n` and paragraph spacing using `\\n\\n\\n`
 - [RawDescriptionCmd2HelpFormatter][cmd2.argparse_utils.RawDescriptionCmd2HelpFormatter] - retains
   any formatting in descriptions and epilogs
 - [RawTextCmd2HelpFormatter][cmd2.argparse_utils.RawTextCmd2HelpFormatter] - retains formatting of

pyproject.toml

@@ -33,7 +33,7 @@ dependencies = [
     "prompt-toolkit>=3.0.52",
     "pyperclip>=1.8.2",
     "rich>=15.0.0",
-    "rich-argparse>=1.7.2",
+    "rich-argparse>=1.8.0",
     "typing-extensions; python_version == '3.10'",
 ]