Skip to content

Commit 6bdb080

Browse files
kinowkinow
committed
Creating a preview of the outline proposed
1 parent c7240b9 commit 6bdb080

24 files changed

+196
-24
lines changed

‎_templates/layout.html

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@
55
<div class="row">
66
<div class="col d-flex flex-row-reverse">
77
<ul class="nav">
8+
<li class="nav-item">
9+
<a class="nav-link" href="https://github.com/common-workflow-language/user_guide/blob/main/CODE_OF_CONDUCT.md">Code of Conduct</a>
10+
</li>
811
<li class="nav-item">
912
<a class="nav-link" href="https://github.com/common-workflow-language/user_guide/blob/main/CONTRIBUTING.md">Contributing</a>
1013
</li>

‎_templates/sidebar-nav-bs.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
<nav class="bd-links d-none d-md-block" id="bd-docs-nav" aria-label="{{ _('Main navigation') }}">
22
<div class="bd-toc-item active">
33
{{ generate_nav_html("sidebar",
4+
startdepth=0,
45
show_nav_level=theme_show_nav_level|int,
56
maxdepth=theme_navigation_depth|int,
67
collapse=theme_collapse_navigation|tobool,

‎basic-concepts.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Basic Concepts
2+
3+
TODO:
4+
5+
- What is CWL, what is an implementation (show or point to a list of implementations), workflow, tool, steps

‎core-concepts/advanced-topics.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Advanced Topics
2+
3+
TODO
4+
5+
- File Formats. Move the **episode 16** about File Formats from the current User Guide here? - https://www.commonwl.org/user_guide/16-file-formats/index.html
6+
- Metadata and Authors - from the **episode 17** from the current User Guide - https://www.commonwl.org/user_guide/17-metadata/index.html
7+
- Testing and Debugging CWL Workflows
8+
- Parallelism (or another title, showing scatter, independent steps, scatter+pickValue, conditionals, etc) - https://github.com/common-workflow-language/user_guide/issues/104
9+
- Data creation / manipulation at runtime (for example at specific mounth paths)
10+
- Consume & Produce CWL objects - https://github.com/common-workflow-language/user_guide/issues/32
11+
- Using containers - https://www.synapse.org/#!Synapse:syn2813589/wiki/401462 & clarify on a common question about using non-docker tools, like singularity
12+
- Features offered by other runners (or runner-specific features)
13+
- Using TypeScript for JS Expressions - https://github.com/umccr/cwl-ica/wiki/TypeScript

‎core-concepts/best-practices.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Best Practices
2+
3+
TODO
4+
5+
- Writing CWL workflows (include existing docs from https://github.com/common-workflow-library/cwl-patterns/blob/main/README.md)
6+
- FAIR best practices with CWL
7+
- Docker best practices with CWL - https://github.com/common-workflow-language/common-workflow-language/issues/347
8+
- Add the **episode Recommended Practices** from the current User Guide here? - https://www.commonwl.org/user_guide/rec-practices/index.html

‎core-concepts/command-line-tool.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# CommandLineTool
2+
3+
TODO
4+
5+
- Spaces in commands https://github.com/common-workflow-language/user_guide/issues/39
6+
- Arguments (tell the reader the different use cases for arguments and inputs, tell them there is a section about inputs)

‎core-concepts/enums.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Enums
2+
3+
TODO
4+
5+
https://github.com/common-workflow-language/user_guide/issues/155
6+
7+
- Maybe show an example with booleans, pros and cons - https://github.com/common-workflow-language/user_guide/issues/89

‎core-concepts/environment-variables.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Environment Variables
2+
3+
TODO
4+
5+
- Covered by the **episode 12** of the current User Guide - https://www.commonwl.org/user_guide/12-env/index.html

‎core-concepts/expression-tool.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# ExpressionTool
2+
3+
TODO

‎core-concepts/expressions.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Expressions
2+
3+
TODO
4+
5+
(maybe not before other concepts? move this to after inputs/outputs/etc?)
6+
7+
- External libraries and expressionLib - https://github.com/common-workflow-language/user_guide/issues/126

‎core-concepts/index.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Core Concepts
2+
3+
```{toctree}
4+
:maxdepth: 2
5+
command-line-tool.md
6+
expressions.md
7+
inputs.md
8+
outputs.md
9+
records.md
10+
enums.md
11+
steps.md
12+
operations.md
13+
expression-tool.md
14+
workflows.md
15+
environment-variables.md
16+
requirements-and-hints.md
17+
advanced-topics.md
18+
best-practices.md
19+
```

‎core-concepts/inputs.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Inputs
2+
3+
TODO
4+
5+
- We can use the **episode 3** from the current User Guide - https://www.commonwl.org/user_guide/03-input/index.html
6+
- Explain its fields, such as default, valueFrom, etc - https://github.com/common-workflow-language/common-workflow-language/issues/359
7+
- The **episode 9** covers Array Inputs - https://www.commonwl.org/user_guide/09-array-inputs/index.html
8+
- The **episode 11** covers Advanced Inputs (records and type unions) - https://www.commonwl.org/user_guide/11-records/index.html
9+
- Exclusive parameters https://github.com/common-workflow-language/user_guide/issues/162
10+
- Optional Inputs https://github.com/common-workflow-language/user_guide/issues/44
11+
- Several ways of defining inputs/arguments to tools and workflows - https://github.com/common-workflow-language/user_guide/issues/33
12+
- The **episode 8** of the current User Guide covers it - https://www.commonwl.org/user_guide/08-arguments/index.html
13+
- Using an input output in another input - https://github.com/common-workflow-language/user_guide/issues/90
14+
- How to use linkMerge - https://github.com/common-workflow-language/user_guide/issues/117 (or maybe move to Advanced?)
15+
- Secondary files - https://github.com/common-workflow-language/common-workflow-language/issues/270

‎core-concepts/operations.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Operations
2+
3+
TODO
4+
5+
https://github.com/common-workflow-language/user_guide/issues/218

‎core-concepts/outputs.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Outputs
2+
3+
TODO
4+
5+
- The **episodes 4, 5, and 6** (?) of the current User Guide covers it - https://www.commonwl.org/user_guide/04-output/index.html & https://www.commonwl.org/user_guide/05-stdout/index.html & https://www.commonwl.org/user_guide/06-params/index.html
6+
- The **episode 10** of the current User Guide covers Array Outputs - https://www.commonwl.org/user_guide/10-array-outputs/index.html
7+
- Creating files at runtime - https://github.com/common-workflow-language/user_guide/issues/134

‎core-concepts/records.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Records
2+
3+
TODO
4+
5+
https://github.com/common-workflow-language/common-workflow-language/issues/202
6+
7+
- Document corner cases & workarounds - https://github.com/common-workflow-language/common-workflow-language/issues/241

‎core-concepts/requirements-and-hints.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Requirements and Hints
2+
3+
TODO
4+
5+
- InlineJavascriptRequirement
6+
- Maybe list cases where it is not really necessary? e.g. https://github.com/common-workflow-language/common-workflow-language/issues/389
7+
- Covered by the **episode 13** of the current User Guide - https://www.commonwl.org/user_guide/13-expressions/index.html
8+
- InitialWorkDirRequirement
9+
- Staging Files (a common topic, and appears in questions on discourse/element... maybe it deserves a more prominent location?)
10+
- Writable inputs - https://github.com/common-workflow-language/user_guide/issues/36
11+
- Creating files at runtime, from **episode 14** of the current User Guide - https://www.commonwl.org/user_guide/14-runtime/index.html
12+
- There is a whole **episode 15** in the current User Guide about it - https://www.commonwl.org/user_guide/15-staging/index.html
13+
- DockerRequirement
14+
- Covered in the **episode 7** of the current User Guide - https://www.commonwl.org/user_guide/07-containers/index.html
15+
- SchemaDefRequirement and input schemas
16+
- The **episode 19** from the current User Guide covers it - https://www.commonwl.org/user_guide/19-custom-types/index.html
17+
- ShellCommandRequirement - https://github.com/common-workflow-language/user_guide/issues/159
18+
- SoftwareRequirement - From the **20** from the current User Guide - episode https://www.commonwl.org/user_guide/20-software-requirements/index.html
19+
- MultipleInputFeatureRequirement
20+
- Also in **episode 24** of the current User Guide - https://www.commonwl.org/user_guide/24_conditional-workflow/index.html
21+
- SubworkflowFeatureRequirement
22+
- Also in **episode 22** of the current User Guide - https://www.commonwl.org/user_guide/22-nested-workflows/index.html
23+
- ScatterFeatureRequirement
24+
- Also in **episode 23** of the current User Guide - https://www.commonwl.org/user_guide/23-scatter-workflow/index.html

‎core-concepts/steps.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Steps
2+
3+
TODO

‎core-concepts/workflows.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Workflows
2+
3+
TODO
4+
5+
- The current User Guide covers it in the **episode 21** - https://www.commonwl.org/user_guide/21-1st-workflow/index.html
6+
- Scatter
7+
- ScatterMethod https://github.com/common-workflow-language/user_guide/issues/29
8+
- Also in the **episode 23** of the current User Guide - https://www.commonwl.org/user_guide/23-scatter-workflow/index.html
9+
- Subworkflows/nested workflows
10+
- Covered in the **episode 22** from the current User Guide - https://www.commonwl.org/user_guide/22-nested-workflows/index.html
11+
- Conditionals https://github.com/common-workflow-language/user_guide/issues/191 & https://github.com/common-workflow-language/user_guide/issues/188
12+
- Also in the **episode 24** of the current User Guide - https://www.commonwl.org/user_guide/24_conditional-workflow/index.html

‎faq.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# FAQ
2+
3+
- https://github.com/common-workflow-language/user_guide/issues/6
4+
- Maybe adapt some of these (or move to a workaround?) https://www.synapse.org/#!Synapse:syn2813589/wiki/401464
5+
- A common question is whether users/devs can use singularity or other containers

‎how-tos.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# How-Tos
2+
3+
TODO
4+
5+
- Use VSCode for writing CWL workflows - https://github.com/arvados/arvados-vscode-cwl-training

‎index.md

Lines changed: 9 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Hello!
66

77
% This is a comment in MyST
88

9-
This guide will introduce you to writing tool wrappers and workflows using the Common Workflow Language (CWL). This guide describes the stable specification, version 1.0. Updates to the guide for more recent versions are ongoing.
9+
This guide will introduce you to writing tool wrappers and workflows using the Common Workflow Language (CWL). This guide describes the latest specification, version 1.2. Updates to the guide for more recent versions are ongoing.
1010

1111
```{note}
1212
<p class="rubric">Contributions and Feedback are Welcome!</p>
@@ -21,12 +21,6 @@ by clicking the "Edit on GitHub" button at the top-right
2121
of the relevant page.
2222
```
2323

24-
```{admonition} Prerequisites
25-
* A text editor
26-
27-
* A CWL runner. It is recommended to start with the [reference implementation][cwltool-install]. The full list of CWL runners is on [the project homepage][cwl-runners-list].
28-
```
29-
3024
You also may be interested in:
3125
1. [A quick tutorial for the subset of YAML used in CWL](/yaml/index.md)
3226
2. [CWL Recommended Practices](/rec-practices/index.md)
@@ -36,28 +30,19 @@ You also may be interested in:
3630
[cwl-runners-list]: https://www.commonwl.org/#Implementations
3731
[cwltool-install]: https://github.com/common-workflow-language/cwltool#install
3832

39-
## Schedule
40-
41-
```{toctree}
42-
:maxdepth: 1
43-
:hidden:
44-
45-
CODE_OF_CONDUCT.md
46-
setup.md
47-
```
33+
## Table of Contents
4834

4935
```{toctree}
5036
:maxdepth: 2
5137
52-
episodes.md
53-
```
54-
55-
```{toctree}
56-
:maxdepth: 1
57-
:hidden:
58-
38+
quick-start.md
39+
prerequisites.md
40+
basic-concepts.md
41+
core-concepts/index.md
42+
how-tos.md
43+
tutorials.md
44+
faq.md
5945
extras.md
60-
LICENSE.md
6146
```
6247

6348
[repo]: https://github.com/common-workflow-language/user_guide/issues

‎prerequisites.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Prerequisites
2+
3+
TODO:
4+
5+
- Install cwltool - https://github.com/common-workflow-language/user_guide/issues/166
6+
- Install Docker
7+
- Clarify local vs container execution - https://github.com/common-workflow-language/user_guide/issues/119
8+
- Use cwl-runner, explain about it, and the virtualenv's - https://github.com/common-workflow-language/user_guide/issues/64 & simple explanation in https://www.synapse.org/#!Synapse:syn2813589/wiki/401462 too

‎quick-start.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Quick start
2+
3+
TODO:
4+
5+
- An under 10 minutes intro to CWL, for users who may have no idea what are CWL, cwltool, workflows, etc.
6+
- We can use text from the **episodes 1 and 2** from the current User Guide - https://www.commonwl.org/user_guide/01-introduction/index.html & https://www.commonwl.org/user_guide/02-1st-example/index.html
7+
- Mention that we can write `CommandLineTool` or `Workflow` as entry point (not sure if other Processes are allowed too? But I think we should focus on cwltool in this user guide). I remember this was confusing for me at first.
8+
- Explain what is a Job Order file. I remember not having a clue when I saw that text the first time.
9+
- Shorter version of https://www.synapse.org/#!Synapse:syn2813589/wiki/401467 ?
10+
- Point out that we use JSON and YAML, maybe add a link to docs to clarify some of the syntax gotchas, like `-` in YAML - https://github.com/common-workflow-language/common-workflow-language/issues/318
11+
- Maybe add the existing **episode YAML** from the current User Guide - https://www.commonwl.org/user_guide/yaml/index.html

‎tutorials.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Tutorials
2+
3+
TODO
4+
5+
- A listing of existing tutorials, in the CWL website, or other repositories/sites
6+
- https://github.com/common-workflow-language/user_guide/issues/160
7+
- Running CWL in Production (on Linux, HPC, with containers, k8s, etc? We can link existing docs)
8+
- rnaseq with CWL - https://github.com/arvados/rnaseq-cwl-training (maybe we could have sections, like bioinformatics+cwl, or use tags, etc?)

0 commit comments

Comments
 (0)