Fix emphasize-lines with runcmd (#280)

* Fix emphasize-lines with runcmd
* Update emphasize-lines in inputs.md
* Fix emphasize lines for the troubleshooting file

Author: kinow

cwl/sphinx/runcmd.py

@@ -169,9 +169,20 @@ def run(self):
                     r = match.group("replacement").replace("\\", "")
                     output = re.sub(p, r, output)
 
+        # Note: Sphinx's CodeBlock directive expects an array of command-line
+        #       output lines: https://github.com/sphinx-doc/sphinx/blob/c51a88da8b7b40e8d8cbdb1fce85ca2346b2b59a/sphinx/directives/code.py#L114
+        #       But the runcmd original code was simply wrapping a string
+        #       containing \n in the text as a one-element array, e.g.
+        #       ["cwltool --debug ...\ncwltool Version..."].
+        #       That caused the output to be correctly rendered, but the
+        #       emphasize-lines directive parameter to fail if the lines were
+        #       anything greater than 0 (as the self.content array had 1 elem).
+        #       See: https://github.com/common-workflow-language/user_guide/issues/269
+        output = output.split("\n")
+
         # Set up our arguments to run the CodeBlock parent run function
         self.arguments[0] = syntax
-        self.content = [output]
+        self.content = output
         node = super(RunCmdDirective, self).run()
 
         return node

src/topics/inputs.md

@@ -222,7 +222,7 @@ In the first example, you can't provide `itemA` without also providing `itemB`.
 
 ```{runcmd} cwltool record.cwl record-job2.yml
 :working-directory: src/_includes/cwl/inputs
-:emphasize-lines: 3, 9-10, 24
+:emphasize-lines: 4, 10-11, 23
 ````
 
 ```{code-block} console
@@ -241,7 +241,7 @@ matching item (`itemC`) is added to the command line and remaining item (`itemD`
 
 ```{runcmd} cwltool record.cwl record-job3.yml
 :working-directory: src/_includes/cwl/inputs
-:emphasize-lines: 9-10, 24
+:emphasize-lines: 9-10, 22
 ````
 
 ```{code-block} console
@@ -266,7 +266,6 @@ that accepts `null` (i.e. no value provided), or any value from an enum.
 :language: cwl
 :caption: "`exclusive-parameter-expressions.cwl`"
 :name: exclusive-parameter-expressions.cwl
-:emphasize-lines: 7, 21-23
 ```
 
 Note how the JavaScript expression uses the value of the exclusive input parameter
@@ -284,7 +283,7 @@ output field (a `string`), resulting in failure when running your workflow.
 
 ```{runcmd} cwltool exclusive-parameter-expressions.cwl
 :working-directory: src/_includes/cwl/inputs
-:emphasize-lines: 6-10
+:emphasize-lines: 5-10
 ```
 
 To correct it, you must remember to use an or operator in your JavaScript expression

src/topics/troubleshooting.md

@@ -29,7 +29,7 @@ create the directory for you if it does not exist already):
 
 ```{runcmd} cwltool --cachedir /tmp/cachedir/ troubleshooting-wf1.cwl
 :working-directory: src/_includes/cwl/troubleshooting
-:emphasize-lines: 12-14, 19-21
+:emphasize-lines: 13-15, 18-20
 ```
 
 The workflow is in the `permanentFail` status due to `step_b` failing to execute the
@@ -53,7 +53,7 @@ Also note that the status of `step_b` is now of success.
 
 ```{runcmd} cwltool --cachedir /tmp/cachedir/ troubleshooting-wf1-stepb-fixed.cwl
 :working-directory: src/_includes/cwl/troubleshooting
-:emphasize-lines: 12, 16-18
+:emphasize-lines: 12-16
 ```
 
 In this example the workflow step `step_a` was not re-evaluated as it had been cached, and