🐛 fix(render): handle formatter subclasses and wrap preformatted blocks

The `RawDescriptionHelpFormatter` check used exact equality, so parsers
with a custom formatter inheriting from it (e.g. combining
`ArgumentDefaultsHelpFormatter` with `RawDescriptionHelpFormatter`)
would lose all newline formatting in epilog/description text.

Preformatted blocks (usage, epilog, description) also lacked text
wrapping in HTML, causing long lines to overflow their container
with a horizontal scrollbar instead of wrapping naturally.

Author: gaborbernat

roots/test-epilog-multiline-subclass/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-epilog-multiline-subclass/index.rst

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

roots/test-epilog-multiline-subclass/parser.py

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

src/sphinx_argparse_cli/__init__.py

@@ -15,10 +15,24 @@ def setup(app: Sphinx) -> dict[str, Any]:
 
     app.add_directive(SphinxArgparseCli.name, SphinxArgparseCli)
     app.add_config_value("sphinx_argparse_cli_prefix_document", False, "env")  # noqa: FBT003
+    app.add_css_file("sphinx_argparse_cli.css")
+    app.connect("build-finished", _write_css)
 
     return {"parallel_read_safe": True}
 
 
+def _write_css(app: Sphinx, exception: Exception | None) -> None:
+    if exception or not app.builder or app.builder.format != "html":
+        return
+    from pathlib import Path  # noqa: PLC0415
+
+    static = Path(app.outdir) / "_static"
+    static.mkdir(parents=True, exist_ok=True)
+    (static / "sphinx_argparse_cli.css").write_text(
+        ".sphinx-argparse-cli-wrap pre { white-space: pre-wrap; word-wrap: break-word; }\n"
+    )
+
+
 __all__ = [
     "__version__",
 ]

src/sphinx_argparse_cli/_logic.py

@@ -145,7 +145,7 @@ def parser(self) -> ArgumentParser:
                 self._parser.prog = new_prog
                 _update_sub_parser_prog(self._parser, old_prog, new_prog)
 
-            self._raw_format = self._parser.formatter_class == RawDescriptionHelpFormatter
+            self._raw_format = issubclass(self._parser.formatter_class, RawDescriptionHelpFormatter)
         return self._parser
 
     def _load_sub_parsers(
@@ -224,7 +224,7 @@ def _pre_format(self, block: None | str) -> None | paragraph | literal_block:
         if block is None:
             return None
         if self._raw_format and "\n" in block:
-            lit = literal_block("", Text(block))
+            lit = literal_block("", Text(block), classes=["sphinx-argparse-cli-wrap"])
             lit["language"] = "none"
             return lit
         return paragraph("", Text(block))
@@ -424,7 +424,7 @@ def _mk_usage(self, parser: ArgumentParser) -> literal_block:
         with self.no_color():
             texts = parser.format_usage()[len("usage: ") :].splitlines()
         texts = [line if at == 0 else f"{' ' * (len(parser.prog) + 1)}{line.lstrip()}" for at, line in enumerate(texts)]
-        return literal_block("", Text("\n".join(texts)))
+        return literal_block("", Text("\n".join(texts)), classes=["sphinx-argparse-cli-wrap"])
 
     @contextmanager
     def no_color(self) -> Iterator[None]:

tests/test_logic.py

@@ -133,6 +133,15 @@ def test_multiline_epilog_as_html(build_outcome: str) -> None:
     assert ref in build_outcome
 
 
+@pytest.mark.sphinx(buildername="html", testroot="epilog-multiline-subclass")
+def test_multiline_epilog_subclass_formatter_as_html(build_outcome: str) -> None:
+    ref = (
+        "This epilog\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: