List of To-Dos in the User Guide

[Mackenzie-OO7]

In conf.py

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

_In cwltests.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 - https://github.com/common-workflow-language/common-workflow-language/issues/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 https://github.com/common-workflow-language/user_guide/issues/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

• [ ] https://github.com/common-workflow-language/user_guide/issues/155
• [ ] Maybe show an example with booleans, pros and cons - https://github.com/common-workflow-language/user_guide/issues/89
• [ ] https://github.com/common-workflow-language/user_guide/issues/386
• [ ] Document corner cases & workarounds - https://github.com/common-workflow-language/common-workflow-language/issues/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. - https://github.com/common-workflow-language/common-workflow-language/issues/359
• [ ] Optional Inputs https://github.com/common-workflow-language/user_guide/issues/44
• [ ] Several ways of defining inputs/arguments to tools and workflows - https://github.com/common-workflow-language/user_guide/issues/33
• [ ] Using an input output in another input - https://github.com/common-workflow-language/user_guide/issues/90
• [ ] How to use linkMerge - https://github.com/common-workflow-language/user_guide/issues/117 (or maybe move to Advanced?)
• [ ] Secondary files - https://github.com/common-workflow-language/common-workflow-language/issues/270

In Topics/Outputs

• [ ] Creating files at runtime - https://github.com/common-workflow-language/user_guide/issues/134

In Topics/Requirements and Hints

• [ ] InlineJavascriptRequirement
• [ ] Maybe list cases where it is not really necessary? e.g. https://github.com/common-workflow-language/common-workflow-language/issues/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 - https://github.com/common-workflow-language/user_guide/issues/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 - https://github.com/common-workflow-language/user_guide/issues/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 https://github.com/common-workflow-language/user_guide/issues/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 https://github.com/common-workflow-language/user_guide/issues/191 & https://github.com/common-workflow-language/user_guide/issues/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