Merge branch 'main' into patch-1

Author: swzCuroverse

CITATION.md

@@ -1,9 +1,13 @@
 # Citation
 
-To cite the Common Workflow Language  and the CWL project in a scholary work, please use:
+To cite the Common Workflow Language project in a scholary work, please use:
 
-Michael R. Crusoe, Sanne Abeln, Alexandru Iosup, Peter Amstutz, John Chilton, Nebojša Tijanić, Hervé Ménager, Stian Soiland-Reyes, Bogdan Gavrilović, Carole Goble, and The CWL Community. 2022. Methods included: standardizing computational reuse and portability with the Common Workflow Language. Commun. ACM 65, 6 (June 2022), 54–63. https://doi.org/10.1145/3486897
+Michael R. Crusoe, Sanne Abeln, Alexandru Iosup, Peter Amstutz, John Chilton, Nebojša Tijanić,
+Hervé Ménager, Stian Soiland-Reyes, Bogdan Gavrilović, Carole Goble, and The CWL Community. 2022.
+Methods Included: Standardizing Computational Reuse and Portability with the Common Workflow Language.
+Commun. ACM 65, 6 (June 2022), 54–63. https://doi.org/10.1145/3486897
 
+```
 @article{10.1145/3486897,
 author = {Crusoe, Michael R. and Abeln, Sanne and Iosup, Alexandru and Amstutz, Peter and Chilton, John and Tijani\'{c}, Neboj\v{s}a and M\'{e}nager, Herv\'{e} and Soiland-Reyes, Stian and Gavrilovi\'{c}, Bogdan and Goble, Carole and Community, The CWL},
 title = {Methods Included: Standardizing Computational Reuse and Portability with the Common Workflow Language},
@@ -22,6 +26,7 @@ month = {may},
 pages = {54–63},
 numpages = {10}
 }
+```
 
 To cite just the CWL standards themselves, please use the following inclusive of the DOI:
 
@@ -32,6 +37,7 @@ Stojanovic, Luka (2016): Common Workflow Language, v1.0. Specification,
 Common Workflow Language working group. https://w3id.org/cwl/v1.0/
 https://dx.doi.org/10.6084/m9.figshare.3115156.v2
 
+```
 @data{cwl,
   doi = {10.6084/m9.figshare.3115156.v2},
   url = {https://doi.org/10.6084/m9.figshare.3115156.v2},
@@ -45,8 +51,9 @@ Luka Stojanovic
   title = {Common Workflow Language, v1.0},
   year = {2016}
 }
+```
 
-# the above is from https://github.com/common-workflow-language/common-workflow-language/blob/main/CITATION
+[//]: # (the above is from https://github.com/common-workflow-language/common-workflow-language/blob/main/CITATION.cff)
 
 Our preferred DOI for the "CWL User Guide" is http://doi.org/10.5281/zenodo.840129
 

CONTRIBUTING.md

@@ -101,11 +101,13 @@ in `Makefile`).
 # Create and activate a virtual environment
 python -m venv venv
 source venv/bin/activate
+# update the version of pip, setuptools, and wheel
+(venv) pip -U pip setuptools wheel
 # Install the dependencies in your virtual environment
-(venv) python -mpip install .[all]
+(venv) pip install .[all]
 # Create the HTML to visualize locally
 (venv) make html
-(venv) firefox _build/index.html
+(venv) open _build/index.html
 # Or you can start a serve that watches for local file changes
 (venv) make watch
 # Open <http://localhost:8000/> in your browser

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

setup.cfg

@@ -32,7 +32,8 @@ packages = find_namespace:
 include_package_data = True
 python_requires = >=3.6
 install_requires =
-  cwl_runner
+  cwltool
+  cwlref-runner
   cwl-utils==0.*
   myst-parser==0.*
   pydata-sphinx-theme==0.*

src/faq.md

@@ -290,7 +290,7 @@ These can be set by using the default field
 input:
   default:true
 ```
-## Concating Strings in Inputs
+## Concatenating Strings in Inputs
 
 The valueFrom field must be used instead of default.
 

src/introduction/prerequisites.md

@@ -54,11 +54,12 @@ environment:
 
 $ python -m venv venv
 $ source venv/bin/activate
+$ (venv) pip install -U pip setuptools wheel
 $ (venv) pip install cwltool
 ```
 
 ```{note}
-You can find the `cwl-runner` source code [here](https://github.com/common-workflow-language/cwltool/tree/main/cwlref-runner).  
+You can find the `cwl-runner` source code [here](https://github.com/common-workflow-language/cwltool/tree/main/cwlref-runner).
 Visit the `cwltool` [documentation](https://github.com/common-workflow-language/cwltool#install)
 for other ways to install `cwltool` with `apt` and `conda`.
 ```

src/topics/file-formats.md

@@ -42,8 +42,8 @@ parameterization.
 :name: sample.yml
 ```
 
-___Note:___ To follow the example below, you need to download the example input file, *file-formats.bam*. The file is available from [https://github.com/common-workflow-language/user_guide/raw/main/_includes/cwl/file-formats/file-formats.bam
-](https://github.com/common-workflow-language/user_guide/raw/main/_includes/cwl/file-formats/file-formats.bam) and can be downloaded e.g. via `wget`:
+___Note:___ To follow the example below, you need to download the example input file, *file-formats.bam*. The file is available from <https://github.com/common-workflow-language/user_guide/raw/main/_includes/cwl/file-formats/file-formats.bam>
+ and can be downloaded e.g. via `wget`:
 
 ```{code-block}
 $ wget https://github.com/common-workflow-language/user_guide/raw/main/_includes/cwl/file-formats/file-formats.bam

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