New updated List of User Guide Issues

[swzCuroverse]

Making a list of existing user guides issues to help with the upcoming Outreachy project and well as help sort out what is left after @kinow recent update work. The new structure ticket maybe have information about where some of these additions will go - can check that here-#226 Also, "nubs" and "To Dos" have been placed as comments in the User Guide itself to let you know where things might be added.

v1.1, v1.2 Features

• Mention version mixing; and explain when and how to use cwl-upgrader, add CWL v1.1, v1.2 features #188
• NetworkAccess: Need example to show how to Indicate whether a process requires outgoing IPv4/IPv6 network access and what happens if not indicated and ]network access is need but isn't available, document NetworkAccess #249

Expanding/Revising Existing Content

In Introduction/Prerequisite

• Include where the cwl-runner source is? Note from Bruno when writing this section - "I couldn't find in PYPI ait points to the CWL project: https://github.com/common-workflow-language/cwltool/tree/main/cwlref-runner", NO CURRENT TICKET FOR THIS , but has a note in the markdown as a TODO

In Introduction/Basic Concepts

• Add a link to the Core Concepts -> Requirements section, NO CURRENT TICKET - but has a note in the markdown as a TODO

In Topics/CommandLineTool

• 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), No existing ticket just a common bottom of the markdown

In Topics/ExpressionTool

• Explain better with more examples (need to get more information for this)

In Topics/Inputs

• Explain its fields, such as default, valueFrom, etc., better document the 'default' and 'valueFrom' fields on WorkflowStepInput common-workflow-language#359
• Exclusive parameters, Example for using expressions with exclusive parameters #162 Maybe fixed by waiting pull request
• Optional Inputs, work around for "self" based input bindings for optional inputs #44
• Several ways of defining inputs/arguments to tools and workflows, https://github.com/common-workflow-languag/user_guide/issues/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

Location-TBD

• Improve Scatter documentation, Improve scatter documentation #232.
• Expand Section on Containers to include Singularity, Improve the user guide documentation about containers & CWL/cwltool #231
• Running cwltool in a container, Improve the user guide documentation about containers & CWL/cwltool #231
• Update and clarify existing docker example, Improve the user guide documentation about containers & CWL/cwltool #231 and Clarity in "Running Tools Inside Docker" #119 , Some suggestions #190
• Explain about running cwltool inside docker containers, Improve the user guide documentation about containers & CWL/cwltool #231
• Make a better example for showing metadata instead of running wordcount on a bam file, Some suggestions #190
• Add content for mutually exclusive inputs, Add to User Guide about mutually exclusive inputs #229
• Show how to extract a specific element from an array, pulling out a specific member of an array #184
• Explain multi-dimensional scattering and give an example, add (sub-)chapter on multi-dimensional scatter #181
• Highlight the major features of cwltool (e.g. --validate, --parallel ), Note: Some of this has been done but some left to do. , Highlight major features of cwltool #166
• Explain Shell Command - Explain ShellCommandRequirement #159 Looks like it should so in the nub of the "4.12. Requirements and Hints"
• Explain how to reference a local script, write up how to reference a local script #158 Note: this doesn't have placement in the new structure - so maybe FAQs?

Formatting Issues

• Table of Contents doesn't show important workflow subsections, User Guide Table of Contents might be too shallow #252
• Extra box on left-hand-side table of contents, mystery checkbox in side-bar #244
• Adjust wording to use Topics instead of Core Concepts in Intro - Navigating the User Guide Mentions Core Concepts Section but it doesn't exist #255

Needs Clarification or More Information

• Explain drawback with docker, explain dockerFile and known drawbacks #239 - Some of this is already explained. in User Guide but not the singularity/docker interaction.
• Guidelines or Best Practices for the scope of command line tools. , https://github.com/common-workflow-language/user_guide/issues
• Example for using expressions with exclusive parameter (an example has to be made for this issue), https://github.com/common-workflow-language/user_guide/issues
• Need to explain how to add conformance tests and/or add them for new example, Adding Testing into the ReadMe or Contributions Files #254
• - [ ] Fix the missing link the graph below (CWL command-line tool.) 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, NO CURRENT TICKET FOR THIS, but it has a note in the markdown as a TODO
• 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, No current ticket for this, but it has a note in the markdown as a TODO
• 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, NO CURRENT TICKET, but it has note in the markdown as a TODO
• 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

May Be Fixed by Outstanding Pull Requests

• Show how to transpile newer Javascript code for ECMAScript 5.1, how to transpile newer Javascript code for ECMAScript 5.1 #245

[swzCuroverse]

I am working on making this master list of tickets. if you are heading to this ticket from Outreachy - the list of open tickets above is not complete. I should have it finished by October 11th 2022. I am trying to also add new tickets as they come to make it a bit of a "living" ticket to help us keep track of what we still need to do.

To clarify and confusion, I just working am working on cleaning up and organizing the tickets. The work described in the tickets themselves are open and available for anyone to work on.

[smyja]

I am working on this - but if you are heading to this ticket from Outreachy - all the above is up to date, it is just not complete. I should have it finished by October 11th 2022. I am trying to also add new tickets as they come to make it a bit of a "living" ticket to help us keep track of where in the User Guide these new issues fit in.

Hey, do you mean you are already resolving every issue or you mean you are still updating the list of issues.

[swzCuroverse]

No, I not doing these. This is just meant to be a issue of all issues that need to be done. I am just taking ownership of moving all the known to-do to this ticket. I wouldn't mind help on that if someone wanted to help on that as well. I will change my comment above to make it clearer.

[smyja]

No, I not doing these. This is just meant to be a issue of all issues that need to be done. I am just taking ownership of moving all the known to-do to this ticket. I wouldn't mind help on that if someone wanted to help on that as well. I will change my comment above to make it clearer.

Okay. Some issues aren't listed here, like the one I raised and was merged. Also the pygments/code highlighting issue isn't here. Should I leave it? I have already started working on it though.

[Fienne]

@swzCuroverse , the issues about fixing missing links under the command line isn't really clear to me. I don't understand where to find and replace the correct links.
Can you please help me out?

[swzCuroverse]

@Fienne I would skip those for now. I need to get more information about that. There is something that @kinow indicated in the read-me about an issue with graphs. I will dig into that a bit more - probably easier for you to look into one of the issues that has a ticket already written. I moved them into the Need More Information section to indicate that so other people don't run into the same problem.

[Fienne]

Alright then. Thank you.

[Timonwa]

Good day @swzCuroverse. is this a list of potential issues that outreach applicants would tackle? Can I pick a few from here and solve them?

[AfiMaameDufie]

Hi @swzCuroverse ,which issue can I pick up to work on?

[ghost]

Hello @swzCuroverse . My name is Emenyi Nelly and I am an Outreachy intern for the current session. Please can an issue be assigned to me to work on, as I am very much interested in documentation.

[paulinebanye]

Hi @swzCuroverse I'm Pauline, an outreachy intern. I'm excited to work on this project. Where do I start?

[swzCuroverse]

Hi all - please pick any ticket you find interesting above or in the general list of tickets. You ca join us on the Matrix channel here if you want guidance in setting up. https://app.element.io/#/room/#docs-training:matrix.org See the contribution guide to get started .

[chrilona]

Hello everyone,Christabel Lona Atieno just joining to learn and grow from this interaction.

[DBAKITA]

Hello @swzCuroverse in reference to the command line tool topic

Topics/CommandLineTool

Spaces in commands , #39
Arguments (tell the reader the different use cases for arguments and inputs, tell them there is a section about inputs), No existing ticket just a common bottom of the markdown

Here is my input:
How do commandlines work
A Command Line Tool is a non-interactive executable program that reads some input, performs a computation, and terminates after producing some output. Command line programs are a flexible unit of code sharing and reuse, unfortunately the syntax and input/output semantics among command line programs is extremely heterogeneous. A common layer for describing the syntax and semantics of programs can reduce this incidental complexity by providing a consistent way to connect programs together. This specification defines the Common Workflow Language (CWL) Command Line Tool Description, a vendor-neutral standard for describing the syntax and input/output semantics of command line programs.

Different use cases for arguments and inputs
Available primitive types are string, int, long, float, double, and null; complex types are array and record; in addition there are special types File, Directory and Any.

The following example demonstrates some input parameters with different types and appearing on the command line in different ways.

First, create a file called inp.cwl, containing the following:

inp.cwl
#!/usr/bin/env cwl-runner

cwlVersion: v1.0
class: CommandLineTool
baseCommand: echo
inputs:
example_flag:
type: boolean
inputBinding:
position: 1
prefix: -f
example_string:
type: string
inputBinding:
position: 3
prefix: --example-string
example_int:
type: int
inputBinding:
position: 2
prefix: -i
separate: false
example_file:
type: File?
inputBinding:
prefix: --file=
separate: false
position: 4

outputs: []

Sometimes tools require additional command line options that don’t correspond exactly to input parameters.

In this example, we will wrap the Java compiler to compile a java source file to a class file. By default, “javac” will create the class files in the same directory as the source file. However, CWL input files (and the directories in which they appear) may be read-only, so we need to instruct “javac” to write the class file to the designated output directory instead.

arguments.cwl
#!/usr/bin/env cwl-runner

cwlVersion: v1.0
class: CommandLineTool
label: Example trivial wrapper for Java 9 compiler
hints:
DockerRequirement:
dockerPull: openjdk:9.0.1-11-slim
baseCommand: javac
arguments: ["-d", $(runtime.outdir)]
inputs:
src:
type: File
inputBinding:
position: 1
outputs:
classfile:
type: File
outputBinding:
glob: "*.class"