Fix CLI argument help with multi-line subcommand text.

When the command funciton docstring spanned multiple lines the
argument help text was getting inserted into the middle of the
command function text.

python/lsst/daf/butler/cli/utils.py

@@ -193,6 +193,14 @@ def addArgumentHelp(doc, helpText):
             doc = doc.split("\f")[0]
 
         doclines = doc.splitlines()
+        # The function's docstring may span multiple lines, so combine the
+        # docstring from all the first lines until a blank line is encountered.
+        # (Lines after the first blank line will be argument help.)
+        while True:
+            if len(doclines) > 1 and doclines[1]:
+                doclines[0] = " ".join((doclines[0], doclines.pop(1).strip()))
+            else:
+                break
         doclines.insert(1, helpText)
         doclines.insert(1, "\n")
         doc = "\n".join(doclines)

tests/test_cliUtils.py

@@ -47,23 +47,36 @@ def test_callMock(self):
 
 class ArgumentHelpGeneratorTestCase(unittest.TestCase):
 
-    @staticmethod
-    @click.command()
-    # Use custom help in the arguments so that any changes to default help text
-    # do not break this test unnecessarily.
-    @repo_argument(help="repo help text")
-    @directory_argument(help="directory help text")
-    def cli():
-        """The cli help message."""
-        pass
+    def testHelp(self):
+        @click.command()
+        # Use custom help in the arguments so that any changes to default help
+        # text do not break this test unnecessarily.
+        @repo_argument(help="repo help text")
+        @directory_argument(help="directory help text")
+        def cli():
+            """The cli help message."""
+            pass
 
-    def test_help(self):
+        self.runTest(cli)
+
+    def testHelpWrapped(self):
+        @click.command()
+        # Use custom help in the arguments so that any changes to default help
+        # text do not break this test unnecessarily.
+        @repo_argument(help="repo help text")
+        @directory_argument(help="directory help text")
+        def cli():
+            """The cli
+            help
+            message."""
+            pass
+        self.runTest(cli)
+
+    def runTest(self, cli):
         """Tests `utils.addArgumentHelp` and its use in repo_argument and
         directory_argument; verifies that the argument help gets added to the
         command fucntion help, and that it's added in the correct order. See
         addArgumentHelp for more details."""
-        runner = LogCliRunner()
-        result = runner.invoke(ArgumentHelpGeneratorTestCase.cli, ["--help"])
         expected = """Usage: cli [OPTIONS] REPO DIRECTORY
 
   The cli help message.
@@ -75,6 +88,8 @@ def test_help(self):
 Options:
   --help  Show this message and exit.
 """
+        runner = LogCliRunner()
+        result = runner.invoke(cli, ["--help"])
         self.assertIn(expected, result.output)