diff --git a/cmd2/__init__.py b/cmd2/__init__.py index 9db123b48..46e837e5e 100644 --- a/cmd2/__init__.py +++ b/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", diff --git a/cmd2/rich_utils.py b/cmd2/rich_utils.py index 19a7a3297..d948f782b 100644 --- a/cmd2/rich_utils.py +++ b/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. diff --git a/docs/features/argument_processing.md b/docs/features/argument_processing.md index a0a577380..ab1e26675 100644 --- a/docs/features/argument_processing.md +++ b/docs/features/argument_processing.md @@ -206,7 +206,7 @@ This command cannot generate tags with no content, like
### 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,13 @@ 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 diff --git a/pyproject.toml b/pyproject.toml index 606a031c3..15f39b761 100644 --- a/pyproject.toml +++ b/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'", ]