Support rendering with argparse.RawDescriptionHelpFormatter (#144)

* Create literal_block for multiline description

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: mayrholu

roots/test-description-multiline/conf.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+extensions = ["sphinx_argparse_cli"]
+nitpicky = True

roots/test-description-multiline/index.rst

@@ -0,0 +1,3 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make

roots/test-description-multiline/parser.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, RawDescriptionHelpFormatter
+
+
+def make() -> ArgumentParser:
+    return ArgumentParser(
+        prog="foo",
+        description="""This description
+spans multiple lines.
+
+  this line is indented.
+    and also this.
+
+Now this should be a separate paragraph.
+""",
+        formatter_class=RawDescriptionHelpFormatter,
+        add_help=False,
+    )

src/sphinx_argparse_cli/_logic.py

@@ -7,6 +7,7 @@
     Action,
     ArgumentParser,
     HelpFormatter,
+    RawDescriptionHelpFormatter,
     _ArgumentGroup,
     _StoreFalseAction,
     _StoreTrueAction,
@@ -148,8 +149,12 @@ def run(self) -> list[Node]:
 
         description = self.options.get("description", self.parser.description)
         if description:
-            desc_paragraph = paragraph("", Text(description))
-            home_section += desc_paragraph
+            if isinstance(self.parser.formatter_class(""), RawDescriptionHelpFormatter) and "\n" in description:
+                lit = literal_block("", Text(description))
+                lit["language"] = "none"
+                home_section += lit
+            else:
+                home_section += paragraph("", Text(description))
         # construct groups excluding sub-parsers
         home_section += self._mk_usage(self.parser)
         for group in self.parser._action_groups:  # noqa: SLF001

tests/test_logic.py

@@ -99,6 +99,15 @@ def test_empty_description_as_text(build_outcome: str) -> None:
     assert build_outcome == "foo - CLI interface\n*******************\n\n   foo\n"
 
 
+@pytest.mark.sphinx(buildername="html", testroot="description-multiline")
+def test_multiline_description_as_html(build_outcome: str) -> None:
+    ref = (
+        "This description\nspans multiple lines.\n\n  this line is indented.\n    and also this.\n\nNow this should be"
+        " a separate paragraph.\n"
+    )
+    assert ref in build_outcome
+
+
 @pytest.mark.sphinx(buildername="text", testroot="complex")
 @pytest.mark.prepare(directive_args=[":usage_width: 100"])
 def test_usage_width_default(build_outcome: str) -> None: