🐛 fix: keep non-paragraph help nodes out of the option line

Whitespace-only help crashed with IndexError because nested_parse
returned no nodes and the code indexed the first one. Help that parsed
to a bullet list or several paragraphs got spliced into the option's
paragraph, which nests <li> inside <p> and drops every paragraph after
the first. An empty :description: override left an empty <p>.

Only a leading paragraph now shares the option line; other nodes go
under the list item as blocks, and blank description or epilog text
renders nothing.

Author: gaborbernat

CHANGELOG.md

@@ -12,6 +12,8 @@ All notable changes to this project will be documented in this file.
 - Leave apostrophes inside words (`don't`, `it's`) alone in help text instead of turning them into broken inline
   literals.
 - Make `:hook:` intercept `parse_intermixed_args()` as well as `parse_args()`.
+- Fix a crash on whitespace-only help text, render help that parses to lists or several paragraphs as blocks under the
+  argument instead of inside its paragraph, and drop the empty paragraph an empty `:description:` produced.
 
 ## 1.13.1
 

roots/test-help-nodes/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-help-nodes/index.rst

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

roots/test-help-nodes/parser.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, RawTextHelpFormatter
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(prog="prog", formatter_class=RawTextHelpFormatter, add_help=False)
+    parser.add_argument("--blank", help="   ")
+    parser.add_argument("--list", help="- item one\n- item two")
+    parser.add_argument("--two", help="first paragraph\n\nsecond paragraph")
+    return parser

src/sphinx_argparse_cli/_logic.py

@@ -48,7 +48,7 @@
 from sphinx.util.logging import getLogger
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator
+    from collections.abc import Callable, Iterator, Sequence
 
     from sphinx.domains.std import StandardDomain
     from sphinx.util.logging import SphinxLoggerAdapter
@@ -196,7 +196,7 @@ def run(self) -> list[Node]:
         return [home_section]
 
     def _pre_format(self, block: str | None) -> paragraph | literal_block | None:
-        if block is None:
+        if block is None or not block.strip():
             return None
         if self._raw_format and "\n" in block:
             lit = literal_block("", Text(block), classes=["sphinx-argparse-cli-wrap"])
@@ -256,13 +256,17 @@ def _mk_option_line(self, action: Action, prefix: str) -> list_item:
         else:
             self._mk_option_name(line, prefix, as_key)
 
+        extra: Sequence[Node] = ()
         if action.help:
-            help_text = load_help_text(action.help)
             temp = paragraph()
-            self.state.nested_parse(StringList(help_text.split("\n")), 0, temp)
-            line += Text(" - ")
-            for content in cast("paragraph", temp.children[0]).children:
-                line += content
+            self.state.nested_parse(StringList(load_help_text(action.help).split("\n")), 0, temp)
+            # only a leading paragraph can share the option's line; anything else becomes a block under it
+            if temp.children and isinstance(temp.children[0], paragraph):
+                line += Text(" - ")
+                line += temp.children[0].children
+                extra = temp.children[1:]
+            else:
+                extra = temp.children
         if (
             "no_default_values" not in self.options
             and action.default is not None
@@ -273,8 +277,9 @@ def _mk_option_line(self, action: Action, prefix: str) -> list_item:
             line += Text(" (default: ")
             line += literal(text=str(action.default).replace(str(Path.cwd()), "{cwd}"))
             line += Text(")")
-        _protect_option_dashes(line)
-        return list_item("", line, ids=[])
+        item = list_item("", line, *extra, ids=[])
+        _protect_option_dashes(item)
+        return item
 
     def _mk_option_name(self, line: paragraph, prefix: str, opt: str) -> None:
         ref_id = self._make_id(f"{prefix}-{opt}")

tests/test_logic.py

@@ -118,7 +118,7 @@ def test_set_description_as_text(build_outcome: str) -> None:
 
 @pytest.mark.sphinx(buildername="text", testroot="description-empty")
 def test_empty_description_as_text(build_outcome: str) -> None:
-    assert build_outcome == "foo - CLI interface\n*******************\n\n\n   foo\n"
+    assert build_outcome == "foo - CLI interface\n*******************\n\n   foo\n"
 
 
 @pytest.mark.sphinx(buildername="html", testroot="description-multiline")
@@ -140,7 +140,7 @@ def test_set_epilog_as_text(build_outcome: str) -> None:
 
 @pytest.mark.sphinx(buildername="text", testroot="epilog-empty")
 def test_empty_epilog_as_text(build_outcome: str) -> None:
-    assert build_outcome == "foo - CLI interface\n*******************\n\n   foo\n\n"
+    assert build_outcome == "foo - CLI interface\n*******************\n\n   foo\n"
 
 
 @pytest.mark.sphinx(buildername="html", testroot="epilog-multiline")
@@ -273,6 +273,40 @@ def test_option_role_as_html(build_outcome: str, warning: StringIO) -> None:
     assert not warning.getvalue()
 
 
+@pytest.mark.sphinx(buildername="text", testroot="help-nodes")
+def test_help_nodes_as_text(build_outcome: str) -> None:
+    assert (
+        build_outcome
+        == """prog - CLI interface
+********************
+
+   prog [--blank BLANK] [--list LIST] [--two TWO]
+
+
+prog options
+============
+
+* **"--blank"** "BLANK"
+
+* **"--list"** "LIST"
+
+  * item one
+
+  * item two
+
+* **"--two"** "TWO" - first paragraph
+
+  second paragraph
+"""
+    )
+
+
+@pytest.mark.sphinx(buildername="html", testroot="help-nodes")
+def test_help_nodes_as_html(build_outcome: str, warning: StringIO) -> None:
+    assert "<p></p>" not in build_outcome
+    assert not warning.getvalue()
+
+
 @pytest.mark.sphinx(buildername="text", testroot="ref-duplicate-label")
 def test_ref_duplicate_label(build_outcome: tuple[str, str], warning: StringIO) -> None:
     assert build_outcome