List of To-Dos in the User Guide

[Mackenzie-OO7]

In conf.py

• maybe write our own lexer to customize tokens, keywords, etc?

In cwl_tests.yml

• The old section 23-scatter-workflow had workflows, but no conformance tests?
  Maybe add them here, they are now in workflows:
  • hello_world.cwl
  • hello_world_to_stdout.cwl
  • scatter-job.cwl
  • scatter-nested-workflow.cwl
  • scatter-two-steps.cwl
  • scatter-workflow.cwl
  • wc-tool.cwl

In Introduction/Basic Concepts

• add a link to the Core Concepts -> Requirements section below?

In Topics/Best Practices

• Writing CWL workflows (include existing docs from https://github.com/common-workflow-library/cwl-patterns/blob/main/README.md)
• FAIR best practices with CWL
• Docker best practices with CWL - capture docker+CWL best practices from Denis Yuen et al. common-workflow-language#347

In Topics/CommandLine Tool

• Fix the missing link the graph below. We cannot have it here as this file is included in two other files. Sphinx prohibits it for the case where this could lead to duplicate anchors in a page (e.g. single-html). :name: command-line-tool-graph
• Fix the missing link the code below. We cannot have it here as this file is included in two other files. Sphinx prohibits it for the case where this could lead to duplicate anchors in a page (e.g. single-html). :name: echo.cwl
• Spaces in commands Add discussion about how command lines work; spaces in options #39
• Arguments (tell the reader the different use cases for arguments and inputs, tell them there is a section about inputs)

In Topics/Custom Types

• more about enums #155
• Maybe show an example with booleans, pros and cons - document how to model a one-or-the-other parameter #89
• rework Record inputs, dependent and mutually exclusive parameters #386
• Document corner cases & workarounds - document how to reuse custom record types (what to do about inputBindings?) common-workflow-language#241

In Topics/Expression Tool

• Explain better with more examples.
• Fix the missing link the graph below. We cannot have it here as this file is included in two other files. Sphinx prohibits it for the case where this could lead to duplicate anchors in a page (e.g. single-html). :name: expression-tool-graph
• Fix the missing link the code below. We cannot have it here as this file is included in two other files. Sphinx prohibits it for the case where this could lead to duplicate anchors in a page (e.g. single-html). :name: uppercase.cwl

In Topics/Inputs

• Explain its fields, such as default, valueFrom, etc. - better document the 'default' and 'valueFrom' fields on WorkflowStepInput common-workflow-language#359
• Optional Inputs work around for "self" based input bindings for optional inputs #44
• Several ways of defining inputs/arguments to tools and workflows - intermediate lesson: workflow design choices and the 7 levels of configuration #33
• Using an input output in another input - advanced lesson: adapt the type of an output for a WorkflowStep input #90
• How to use linkMerge - advanced: extended discussion about linkMerge #117 (or maybe move to Advanced?)
• Secondary files - secondaryFiles are undocumented common-workflow-language#270

In Topics/Outputs

• Creating files at runtime - build on lesson 14 "Creating Files at Runtime", but for directories #134

In Topics/Requirements and Hints

• InlineJavascriptRequirement
• Maybe list cases where it is not really necessary? e.g. document in user guide that multiple parameter references and string concatenation are possible without InlineJavascript common-workflow-language#389
• Covered by the episode 13 of the current User Guide - https://www.commonwl.org/user_guide/13-expressions/index.html
• InitialWorkDirRequirement
• Staging Files (a common topic, and appears in questions on discourse/element... maybe it deserves a more prominent location?)
• Writable inputs - advanced file staging: writable inputs #36
• Creating files at runtime, from episode 14 of the current User Guide - https://www.commonwl.org/user_guide/14-runtime/index.html
• There is a whole episode 15 in the current User Guide about it - https://www.commonwl.org/user_guide/15-staging/index.html
• DockerRequirement
• Covered in the episode 7 of the current User Guide - https://www.commonwl.org/user_guide/07-containers/index.html
• SchemaDefRequirement and input schemas
• The episode 19 from the current User Guide covers it - https://www.commonwl.org/user_guide/19-custom-types/index.html
• ShellCommandRequirement - Explain ShellCommandRequirement #159
• SoftwareRequirement - From the 20 from the current User Guide - episode https://www.commonwl.org/user_guide/20-software-requirements/index.html
• MultipleInputFeatureRequirement
• Also in episode 24 of the current User Guide - https://www.commonwl.org/user_guide/24_conditional-workflow/index.html
• SubworkflowFeatureRequirement
• Also in episode 22 of the current User Guide - https://www.commonwl.org/user_guide/22-nested-workflows/index.html
• ScatterFeatureRequirement
• Also in episode 23 of the current User Guide - https://www.commonwl.org/user_guide/23-scatter-workflow/index.html

In Topics/Workflows

• Fix the missing link the graph below. We cannot have it here as this file is included in two other files. Sphinx prohibits it for the case where this could lead to duplicate anchors in a page (e.g. single-html). :name: workflow-graph
• Fix the missing link the code below. We cannot have it here as this file is included in two other files. Sphinx prohibits it for the case where this could lead to duplicate anchors in a page (e.g. single-html). :name: echo-uppercase.cwl
• Fix the missing link the code below. We cannot have it here as this file is included in two other files. Sphinx prohibits it for the case where this could lead to duplicate anchors in a page (e.g. single-html). :name: echo-uppercase-single-file.cwl
• add a link to the page about SubworkflowFeatureRequirement
• The link below is for a previous commit with the workflow above. Ideally, I think we should either use cwltoolor Python to add the graph here. Or, maybe re-create the graph for the latest main version?
• Scatter
• ScatterMethod Explain ScatterMethod #29
• Also in the episode 23 of the current User Guide - https://www.commonwl.org/user_guide/workflows/index.html
• Subworkflows/nested workflows
• Covered in the episode 22 from the current User Guide - https://www.commonwl.org/user_guide/workflows/index.html
• Conditionals todos for conditional workflow documentation #191 & add CWL v1.1, v1.2 features #188
• Also in the episode 24 of the current User Guide - https://www.commonwl.org/user_guide/24_conditional-workflow/index.html

[Mackenzie-OO7]

@swzCuroverse Here's a list of the To-Do placeholders throughout the doc.

[kinow]

Thanks for gathering everything here. I had no idea there were so many 😯

[swzCuroverse]

Thank you for doing this @Mackenzie-OO7. Let's me see if any of these have new tickets that didn't get marked in the todo.

[steph237]

Greetings @kinow and @swzCuroverse I will like to work on some of the ToDos listed here like in the Introduction section "add a link to the Core Concepts -> Requirements section". I will like like to know where the content of the Core Concepts is.
Thanks

[Mackenzie-OO7]

Greetings @kinow and @swzCuroverse I will like to work on some of the ToDos listed here like in the Introduction section "add a link to the Core Concepts -> Requirements section". I will like like to know where the content of the Core Concepts is. Thanks

Hello,
"Core Concepts" was changed to Topics. see common-workflow-language/common-workflow-language#258