From 2be017b889cbf2da686ea7d63c27cfe981c2f575 Mon Sep 17 00:00:00 2001 From: "Bruno P. Kinoshita" Date: Tue, 5 Apr 2022 20:09:47 +1200 Subject: [PATCH] Add sphinx, myst, and the theme used in pandas docs --- .gitignore | 1 + .../index.md | 6 +- .../index.md | 52 +- _episodes/03-input.md => 03-input/index.md | 33 +- _episodes/04-output.md => 04-output/index.md | 28 +- _episodes/05-stdout.md => 05-stdout/index.md | 22 +- _episodes/06-params.md => 06-params/index.md | 28 +- .../index.md | 33 +- .../08-arguments.md => 08-arguments/index.md | 24 +- .../index.md | 24 +- .../index.md | 24 +- .../11-records.md => 11-records/index.md | 38 +- _episodes/12-env.md => 12-env/index.md | 22 +- .../index.md | 33 +- .../14-runtime.md => 14-runtime/index.md | 32 +- .../15-staging.md => 15-staging/index.md | 22 +- .../index.md | 26 +- .../17-metadata.md => 17-metadata/index.md | 23 +- .../index.md | 34 +- .../index.md | 15 +- .../index.md | 34 +- .../index.md | 26 +- .../index.md | 55 +- .../index.md | 13 +- CODE_OF_CONDUCT.md | 9 +- CONTRIBUTING.md | 14 +- LICENSE.md | 7 +- Makefile | 151 +- README.md | 4 +- _episodes/.gitkeep | 0 _extras/.gitkeep | 0 _includes/aio-script.md | 13 +- _includes/all_keypoints.html | 10 +- _includes/base_path.html | 18 +- _includes/carpentries.html | 10 +- _includes/episode_break.html | 4 +- _includes/episode_keypoints.html | 4 +- _includes/episode_navbar.html | 22 +- _includes/episode_overview.html | 4 +- _includes/gh_variables.html | 32 +- _includes/javascript.html | 4 +- _includes/lesson_footer.html | 7 +- _includes/life_cycle.html | 4 +- _includes/links.md | 17 +- _includes/main_title.html | 7 +- _includes/manual_episode_order.html | 120 +- _includes/navbar.html | 28 +- _includes/syllabus.html | 18 +- _includes/workshop_ad.html | 4 +- _includes/workshop_footer.html | 4 +- _layouts/base.html | 49 - _layouts/break.html | 10 - _layouts/episode.html | 11 - _layouts/lesson.html | 8 - _layouts/page.html | 7 - _layouts/reference.html | 6 - _layouts/workshop.html | 55 - .../favicons/cwl/android-icon-144x144.png | Bin 0 -> 5723 bytes .../favicons/cwl/android-icon-192x192.png | Bin 0 -> 6441 bytes .../favicons/cwl/android-icon-36x36.png | Bin 0 -> 1752 bytes .../favicons/cwl/android-icon-48x48.png | Bin 0 -> 2023 bytes .../favicons/cwl/android-icon-72x72.png | Bin 0 -> 2845 bytes .../favicons/cwl/android-icon-96x96.png | Bin 0 -> 3806 bytes .../favicons/cwl/apple-icon-180x180.png | Bin 0 -> 7258 bytes .../favicons/cwl/apple-icon-precomposed.png | Bin 0 -> 6828 bytes _static/images/favicons/cwl/apple-icon.png | Bin 0 -> 6828 bytes .../favicons/cwl/apple-touch-icon-114x114.png | Bin 0 -> 4285 bytes .../favicons/cwl/apple-touch-icon-120x120.png | Bin 0 -> 4559 bytes .../favicons/cwl/apple-touch-icon-144x144.png | Bin 0 -> 5723 bytes .../favicons/cwl/apple-touch-icon-152x152.png | Bin 0 -> 5899 bytes .../favicons/cwl/apple-touch-icon-57x57.png | Bin 0 -> 2342 bytes .../favicons/cwl/apple-touch-icon-60x60.png | Bin 0 -> 2358 bytes .../favicons/cwl/apple-touch-icon-72x72.png | Bin 0 -> 2845 bytes .../favicons/cwl/apple-touch-icon-76x76.png | Bin 0 -> 3001 bytes _static/images/favicons/cwl/favicon-128.png | Bin 0 -> 5083 bytes _static/images/favicons/cwl/favicon-16x16.png | Bin 0 -> 1020 bytes .../images/favicons/cwl/favicon-196x196.png | Bin 0 -> 8714 bytes _static/images/favicons/cwl/favicon-32x32.png | Bin 0 -> 1581 bytes _static/images/favicons/cwl/favicon-96x96.png | Bin 0 -> 3806 bytes _static/images/favicons/cwl/favicon.ico | Bin 0 -> 1086 bytes .../images/favicons/cwl/ms-icon-144x144.png | Bin 0 -> 5723 bytes .../images/favicons/cwl/ms-icon-150x150.png | Bin 0 -> 5856 bytes .../images/favicons/cwl/ms-icon-310x310.png | Bin 0 -> 17278 bytes _static/images/favicons/cwl/ms-icon-70x70.png | Bin 0 -> 2759 bytes .../images/logos/cwl/CWL-Logo-HD-cropped2.png | Bin 0 -> 41476 bytes _static/images/logos/cwl/cwl-icon.png | Bin 0 -> 7258 bytes _static/switcher.json | 7 + _templates/layout.html | 13 + aio.md | 14 +- assets/css/bootstrap-theme.css | 587 -- assets/css/bootstrap-theme.css.map | 1 - assets/css/bootstrap.css | 6835 ----------------- assets/css/bootstrap.css.map | 1 - assets/css/lesson.scss | 292 - assets/css/syntax.css | 69 - assets/js/bootstrap.min.js | 6 - assets/js/jquery.min.js | 6 - assets/js/jquery.min.map | 1 - assets/js/lesson.js | 56 - bin/boilerplate/_episodes/01-introduction.md | 3 +- bin/boilerplate/_extras/about.md | 6 +- bin/boilerplate/_extras/discuss.md | 3 +- bin/boilerplate/_extras/figures.md | 11 +- bin/boilerplate/_extras/guide.md | 3 +- bin/boilerplate/aio.md | 7 +- bin/boilerplate/index.md | 5 +- bin/boilerplate/reference.md | 3 +- bin/boilerplate/setup.md | 3 +- conf.py | 168 + episodes.md | 29 + extras.md | 10 + index.md | 79 +- make.bat | 35 + _extras/miscellaneous.md => misc/index.md | 46 +- .../index.md | 9 +- reference.md | 10 +- requirements.txt | 4 + setup.md | 8 +- _extras/yaml.md => yaml/index.md | 35 +- 119 files changed, 902 insertions(+), 8772 deletions(-) rename _episodes/01-introduction.md => 01-introduction/index.md (95%) rename _episodes/02-1st-example.md => 02-1st-example/index.md (85%) rename _episodes/03-input.md => 03-input/index.md (92%) rename _episodes/04-output.md => 04-output/index.md (89%) rename _episodes/05-stdout.md => 05-stdout/index.md (83%) rename _episodes/06-params.md => 06-params/index.md (93%) rename _episodes/07-containers.md => 07-containers/index.md (91%) rename _episodes/08-arguments.md => 08-arguments/index.md (91%) rename _episodes/09-array-inputs.md => 09-array-inputs/index.md (88%) rename _episodes/10-array-outputs.md => 10-array-outputs/index.md (81%) rename _episodes/11-records.md => 11-records/index.md (86%) rename _episodes/12-env.md => 12-env/index.md (85%) rename _episodes/13-expressions.md => 13-expressions/index.md (92%) rename _episodes/14-runtime.md => 14-runtime/index.md (88%) rename _episodes/15-staging.md => 15-staging/index.md (87%) rename _episodes/16-file-formats.md => 16-file-formats/index.md (92%) rename _episodes/17-metadata.md => 17-metadata/index.md (86%) rename _episodes/19-custom-types.md => 19-custom-types/index.md (89%) rename _episodes/20-software-requirements.md => 20-software-requirements/index.md (93%) rename _episodes/21-1st-workflow.md => 21-1st-workflow/index.md (91%) rename _episodes/22-nested-workflows.md => 22-nested-workflows/index.md (94%) rename _episodes/23-scatter-workflow.md => 23-scatter-workflow/index.md (87%) rename _episodes/24_conditional-workflow.md => 24_conditional-workflow/index.md (96%) delete mode 100644 _episodes/.gitkeep delete mode 100644 _extras/.gitkeep delete mode 100644 _layouts/base.html delete mode 100644 _layouts/break.html delete mode 100644 _layouts/episode.html delete mode 100644 _layouts/lesson.html delete mode 100644 _layouts/page.html delete mode 100644 _layouts/reference.html delete mode 100644 _layouts/workshop.html create mode 100644 _static/images/favicons/cwl/android-icon-144x144.png create mode 100644 _static/images/favicons/cwl/android-icon-192x192.png create mode 100644 _static/images/favicons/cwl/android-icon-36x36.png create mode 100644 _static/images/favicons/cwl/android-icon-48x48.png create mode 100644 _static/images/favicons/cwl/android-icon-72x72.png create mode 100644 _static/images/favicons/cwl/android-icon-96x96.png create mode 100644 _static/images/favicons/cwl/apple-icon-180x180.png create mode 100644 _static/images/favicons/cwl/apple-icon-precomposed.png create mode 100644 _static/images/favicons/cwl/apple-icon.png create mode 100644 _static/images/favicons/cwl/apple-touch-icon-114x114.png create mode 100644 _static/images/favicons/cwl/apple-touch-icon-120x120.png create mode 100644 _static/images/favicons/cwl/apple-touch-icon-144x144.png create mode 100644 _static/images/favicons/cwl/apple-touch-icon-152x152.png create mode 100644 _static/images/favicons/cwl/apple-touch-icon-57x57.png create mode 100644 _static/images/favicons/cwl/apple-touch-icon-60x60.png create mode 100644 _static/images/favicons/cwl/apple-touch-icon-72x72.png create mode 100644 _static/images/favicons/cwl/apple-touch-icon-76x76.png create mode 100644 _static/images/favicons/cwl/favicon-128.png create mode 100644 _static/images/favicons/cwl/favicon-16x16.png create mode 100644 _static/images/favicons/cwl/favicon-196x196.png create mode 100644 _static/images/favicons/cwl/favicon-32x32.png create mode 100644 _static/images/favicons/cwl/favicon-96x96.png create mode 100644 _static/images/favicons/cwl/favicon.ico create mode 100644 _static/images/favicons/cwl/ms-icon-144x144.png create mode 100644 _static/images/favicons/cwl/ms-icon-150x150.png create mode 100644 _static/images/favicons/cwl/ms-icon-310x310.png create mode 100644 _static/images/favicons/cwl/ms-icon-70x70.png create mode 100644 _static/images/logos/cwl/CWL-Logo-HD-cropped2.png create mode 100644 _static/images/logos/cwl/cwl-icon.png create mode 100644 _static/switcher.json create mode 100644 _templates/layout.html delete mode 100644 assets/css/bootstrap-theme.css delete mode 100644 assets/css/bootstrap-theme.css.map delete mode 100644 assets/css/bootstrap.css delete mode 100644 assets/css/bootstrap.css.map delete mode 100644 assets/css/lesson.scss delete mode 100644 assets/css/syntax.css delete mode 100644 assets/js/bootstrap.min.js delete mode 100644 assets/js/jquery.min.js delete mode 100644 assets/js/jquery.min.map delete mode 100644 assets/js/lesson.js create mode 100644 conf.py create mode 100644 episodes.md create mode 100644 extras.md create mode 100644 make.bat rename _extras/miscellaneous.md => misc/index.md (91%) rename _extras/recommended-practices.md => rec-practices/index.md (96%) create mode 100644 requirements.txt rename _extras/yaml.md => yaml/index.md (90%) diff --git a/.gitignore b/.gitignore index 27af20da..192674a9 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ _site .Rhistory .RData +_build/ diff --git a/_episodes/01-introduction.md b/01-introduction/index.md similarity index 95% rename from _episodes/01-introduction.md rename to 01-introduction/index.md index d070f85c..7963a024 100644 --- a/_episodes/01-introduction.md +++ b/01-introduction/index.md @@ -1,5 +1,4 @@ --- -title: "Introduction" teaching: 0 exercises: 0 questions: @@ -14,6 +13,8 @@ keypoints: - "Descriptions in CWL aid portability between environments" --- +# Introduction + CWL is a way to describe command line tools and connect them together to create workflows. Because CWL is a specification and not a specific piece of software, tools and workflows described using CWL are portable across a variety @@ -29,4 +30,5 @@ vendors. CWL is well suited for describing large-scale workflows in cluster, cloud and high performance computing environments where tasks are scheduled in parallel across many nodes. -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/02-1st-example.md b/02-1st-example/index.md similarity index 85% rename from _episodes/02-1st-example.md rename to 02-1st-example/index.md index d1e5654c..16cf0326 100644 --- a/_episodes/02-1st-example.md +++ b/02-1st-example/index.md @@ -1,5 +1,4 @@ --- -title: "First Example" teaching: 5 exercises: 0 questions: @@ -13,35 +12,38 @@ keypoints: - "Input values are specified in a separate YAML file." - "The tool description and input files are provided as arguments to a CWL runner." --- + +# First Example + The simplest "hello world" program. This accepts one input parameter, writes a message to the terminal or job log, and produces no permanent output. CWL documents are written in [JSON][json] or [YAML][yaml], or a mix of the two. We will use YAML throughout this guide. If you are not familiar with YAML, you may find it helpful to refer to -[this quick tutorial for the subset of YAML used in CWL]({{ page.root }}{% link _extras/yaml.md %}). +[this quick tutorial for the subset of YAML used in CWL](/yaml/index.md). First, create a file called `1st-tool.cwl`, containing the boxed text below. It will help you to use a text editor that can be specified to produce text in YAML or JSON. Whatever text editor you use, the indents you see should not be created using tabs. *1st-tool.cwl* -~~~ -{% include cwl/02-1st-example/1st-tool.cwl %} -~~~ -{: .source} + +```{literalinclude} /_includes/cwl/02-1st-example/1st-tool.cwl +:language: yaml +``` Next, create a file called `echo-job.yml`, containing the following boxed text, which will describe the input of a run: *echo-job.yml* -~~~ -{% include cwl/02-1st-example/echo-job.yml %} -~~~ -{: .source} + +```{literalinclude} /_includes/cwl/02-1st-example/echo-job.yml +:language: yaml +``` Now, invoke `cwl-runner` with the tool wrapper `1st-tool.cwl` and the input object echo-job.yml on the command line. The command is `cwl-runner 1st-tool.cwl echo-job.yml`. The boxed text below shows this command and the expected output. -~~~ +```bash $ cwl-runner 1st-tool.cwl echo-job.yml [job 1st-tool.cwl] /tmp/tmpmM5S_1$ echo \ 'Hello world!' @@ -50,43 +52,39 @@ Hello world! {} Final process status is success -~~~ -{: .output} +``` The command `cwl-runner 1st-tool.cwl echo-job.yml` is an example of a general form that you will often come across while using CWL. The general form is `cwl-runner [tool-or-workflow-description] [input-job-settings]` What's going on here? Let's break down the contents of `1st-tool.cwl`: -~~~ +```yaml cwlVersion: v1.0 class: CommandLineTool -~~~ -{: .source} +``` The `cwlVersion` field indicates the version of the CWL spec used by the document. The `class` field indicates this document describes a command line tool. -~~~ +```yaml baseCommand: echo -~~~ -{: .source} +``` The `baseCommand` provides the name of program that will actually run (`echo`). `echo` is a built-in program in the bash and C shells. -~~~ +```yaml inputs: message: type: string inputBinding: position: 1 -~~~ -{: .source} +``` The `inputs` section describes the inputs of the tool. This is a mapped list of input parameters -(see the [YAML Guide]({{ page.root }}{% link _extras/yaml.md %}#maps) for more about the format) +(see the [YAML Guide](/yaml/index.md) for more about the format) and each parameter includes an identifier, a data type, and optionally an `inputBinding`. @@ -95,13 +93,13 @@ on the command line. In this example, the `position` field indicates where it should appear on the command line. -~~~ +```yaml outputs: [] -~~~ -{: .source} +``` This tool has no formal output, so the `outputs` section is an empty list. [echo]: http://www.linfo.org/echo.html -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/03-input.md b/03-input/index.md similarity index 92% rename from _episodes/03-input.md rename to 03-input/index.md index 568f3307..42f24814 100644 --- a/_episodes/03-input.md +++ b/03-input/index.md @@ -1,5 +1,4 @@ --- -title: "Essential Input Parameters" teaching: 10 exercises: 0 questions: @@ -14,6 +13,8 @@ keypoints: appears in the command." --- +# Essential Input Parameters + The `inputs` of a tool is a list of input parameters that control how to run the tool. Each parameter has an `id` for the name of parameter, and `type` describing what types of values are valid for that parameter. @@ -30,19 +31,17 @@ First, create a file called inp.cwl, containing the following: *inp.cwl* -~~~ -{% include cwl/03-input/inp.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/03-input/inp.cwl +:language: yaml +``` Create a file called inp-job.yml: *inp-job.yml* -~~~ -{% include cwl/03-input/inp-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/03-input/inp-job.yml +:language: yaml +``` Notice that "example_file", as a `File` type, must be provided as an object with the fields `class: File` and `path`. @@ -63,14 +62,15 @@ $ cwl-runner inp.cwl inp-job.yml {} Final process status is success ~~~ -{: .output} -> ## Where did those `/tmp` paths come from? + +```{note} +>

Where did those `/tmp` paths come from?

> > The CWL reference runner (cwltool) and other runners create temporary > directories with symbolic ("soft") links to your input files to ensure that > the tools aren't accidentally accessing files that were not explicitly > specified -{: .callout} +``` The field `inputBinding` is optional and indicates whether and how the input parameter should be appear on the tool's command line. If @@ -84,7 +84,6 @@ example_flag: position: 1 prefix: -f ~~~ -{: .source} Boolean types are treated as a flag. If the input parameter "example_flag" is "true", then `prefix` will be added to the @@ -97,7 +96,6 @@ example_string: position: 3 prefix: --example-string ~~~ -{: .source} String types appear on the command line as literal values. The `prefix` is optional, if provided, it appears as a separate argument on the @@ -112,7 +110,6 @@ example_int: prefix: -i separate: false ~~~ -{: .source} Integer (and floating point) types appear on the command line with decimal text representation. When the option `separate` is false (the @@ -128,7 +125,6 @@ example_file: separate: false position: 4 ~~~ -{: .source} File types appear on the command line as the path to the file. When the parameter type ends with a question mark `?` it indicates that the @@ -138,7 +134,7 @@ parameter were not provided in the input, nothing would appear on the command line. Input files are read-only. If you wish to update an input file, you must -[first copy it to the output directory]({{ page.root }}/15-staging/). +[first copy it to the output directory](/15-staging/index.md). The value of `position` is used to determine where parameter should appear on the command line. Positions are relative to one another, not @@ -151,4 +147,5 @@ is optional. The default position is 0. The `baseCommand` field will always appear in the final command line before the parameters. [touch]: http://www.linfo.org/touch.html -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/04-output.md b/04-output/index.md similarity index 89% rename from _episodes/04-output.md rename to 04-output/index.md index 1283bd56..f5fc36b4 100644 --- a/_episodes/04-output.md +++ b/04-output/index.md @@ -1,5 +1,4 @@ --- -title: "Returning Output Files" teaching: 10 exercises: 0 questions: @@ -13,6 +12,9 @@ keypoints: output parameter." - "Wildcards are allowed in the `glob` field." --- + +# Returning Output Files + The `outputs` of a tool is a list of output parameters that should be returned after running the tool. Each parameter has an `id` for the name of parameter, and `type` describing what types of values are valid for @@ -26,26 +28,25 @@ themselves, or come from examining the content of those files. The following example demonstrates how to return a file that has been extracted from a tar file. -> ## Passing mandatory arguments to the `baseCommand` +```{note} +>

Passing mandatory arguments to the `baseCommand`

> > In previous examples, the `baseCommand` was just a string, with any arguments passed as CWL inputs. > Instead of a single string we can use an _array of strings_. The first element is the command to run, and > any subsequent elements are mandatory command line arguments -{: .callout} +``` *tar.cwl* -~~~ -{% include cwl/04-output/tar.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/04-output/tar.cwl +:language: yaml +``` *tar-job.yml* -~~~ -{% include cwl/04-output/tar-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/04-output/tar-job.yml +:language: yaml +``` Next, create a tar file for the example and invoke `cwl-runner` with the tool wrapper and the input object on the command line: @@ -69,7 +70,6 @@ $ cwl-runner tar.cwl tar-job.yml } Final process status is success ~~~ -{: .output} The field `outputBinding` describes how to set the value of each output parameter. @@ -81,9 +81,9 @@ outputs: outputBinding: glob: hello.txt ~~~ -{: .source} The `glob` field consists of the name of a file in the output directory. If you don't know name of the file in advance, you can use a wildcard pattern like `glob: '*.txt'`. -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/05-stdout.md b/05-stdout/index.md similarity index 83% rename from _episodes/05-stdout.md rename to 05-stdout/index.md index c1fc1467..6a0342ad 100644 --- a/_episodes/05-stdout.md +++ b/05-stdout/index.md @@ -1,5 +1,4 @@ --- -title: "Capturing Standard Output" teaching: 10 exercises: 0 questions: @@ -10,23 +9,24 @@ keypoints: - "Use the `stdout` field to specify a filename to capture streamed output." - "The corresponding output parameter must have `type: stdout`." --- + +# Capturing Standard Output + To capture a tool's standard output stream, add the `stdout` field with the name of the file where the output stream should go. Then add `type: stdout` on the corresponding output parameter. *stdout.cwl* -~~~ -{% include cwl/05-stdout/stdout.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/05-stdout/stdout.cwl +:language: yaml +``` *echo-job.yml* -~~~ -{% include cwl/05-stdout/echo-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/05-stdout/echo-job.yml +:language: yaml +``` Now invoke `cwl-runner` providing the tool wrapper and the input object on the command line: @@ -49,5 +49,5 @@ $ cwl-runner stdout.cwl echo-job.yml Final process status is success ~~~ -{: .output} -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/06-params.md b/06-params/index.md similarity index 93% rename from _episodes/06-params.md rename to 06-params/index.md index c97e48aa..333f049f 100644 --- a/_episodes/06-params.md +++ b/06-params/index.md @@ -1,5 +1,4 @@ --- -title: "Parameter References" teaching: 10 exercises: 0 questions: @@ -10,6 +9,9 @@ keypoints: - "Some fields permit parameter references enclosed in `$(...)`." - "References are written using a subset of Javascript syntax." --- + +# Parameter References + In a previous example, we extracted a file using the "tar" program. However, that example was very limited because it assumed that the file we were interested in was called "hello.txt", and this was written into the @@ -22,17 +24,15 @@ the file to extract. *tar-param.cwl* -~~~ -{% include cwl/06-params/tar-param.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/06-params/tar-param.cwl +:language: yaml +``` *tar-param-job.yml* -~~~ -{% include cwl/06-params/tar-param-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/06-params/tar-param-job.yml +:language: yaml +``` Create your input files and invoke `cwl-runner` with the tool wrapper and the input object on the command line: @@ -57,7 +57,6 @@ $ cwl-runner tar-param.cwl tar-param-job.yml } Final process status is success ~~~ -{: .output} Certain fields permit parameter references which are enclosed in `$(...)`. These are evaluated and replaced with value being referenced. @@ -69,7 +68,6 @@ outputs: outputBinding: glob: $(inputs.extractfile) ~~~ -{: .source} References are written using a subset of Javascript syntax. In this example, `$(inputs.extractfile)`, `$(inputs["extractfile"])`, and @@ -83,7 +81,8 @@ input file you must reference the path field on a file object; to reference the path to the tar file in the above example you would write `$(inputs.tarfile.path)`. -> ## Where are parameter references allowed? +```{note} +>

Where are parameter references allowed?

> You can only use parameter references in certain fields. These are: > > - From [`CommandLineTool`](http://www.commonwl.org/v1.0/CommandLineTool.html#CommandLineTool) @@ -132,6 +131,7 @@ reference the path to the tar file in the above example you would write > - From `EnvVarRequirement` > - From [EnvironmentDef](http://www.commonwl.org/v1.0/CommandLineTool.html#EnvironmentDef) > - `envValue` -{: .callout } +``` -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/07-containers.md b/07-containers/index.md similarity index 91% rename from _episodes/07-containers.md rename to 07-containers/index.md index 5439b1d5..95bc3afb 100644 --- a/_episodes/07-containers.md +++ b/07-containers/index.md @@ -1,5 +1,4 @@ --- -title: "Running Tools Inside Docker" teaching: 10 exercises: 0 questions: @@ -12,6 +11,9 @@ a tool." - "Specify a Docker image for a tool with `DockerRequirement` in the `hints` section." --- + +# Running Tools Inside Docker + [Docker][docker] containers simplify software installation by providing a complete known-good runtime for software and its dependencies. However, containers are also purposefully isolated from the host system, so in @@ -23,7 +25,7 @@ management while avoiding the complexity of invoking and managing Docker containers. One of the responsibilities of the CWL runner is to adjust the paths of -input files to reflect the location where they appear inside the container. +input files to reflect the location where they appear inside the container. This example runs a simple Node.js script inside a Docker container which will @@ -31,17 +33,15 @@ then print "Hello World" to the standard output. *docker.cwl* -~~~ -{% include cwl/07-containers/docker.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/07-containers/docker.cwl +:language: yaml +``` *docker-job.yml* -~~~ -{% include cwl/07-containers/docker-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/07-containers/docker-job.yml +:language: yaml +``` Before we run this, lets just break it down and see what some bits do. Most of this has been explained in previous sections, the only part that is really new is the `dockerRequirement` @@ -53,13 +53,12 @@ hints: DockerRequirement: dockerPull: node:slim ~~~ -{: .source} -`baseCommand: node` tells CWL that we will be running this command in a container. We -then need to specify some `hints` for how to find the container we want. In this case we list +`baseCommand: node` tells CWL that we will be running this command in a container. We +then need to specify some `hints` for how to find the container we want. In this case we list just our requirements for the docker container in `DockerRequirements`. The `dockerPull:` parameter takes the same value that you would pass to a `docker pull` command. That is, -the name of the container image (you can even specify the tag, which is good idea for +the name of the container image (you can even specify the tag, which is good idea for best practises when using containers for reproducible research). In this case we have used a container called `node:slim`. @@ -100,10 +99,9 @@ Final process status is success $ cat output.txt Hello World ~~~ -{: .output} Notice the CWL runner has constructed a Docker command line to run the -script. +script. In this example, the path to the script `hello.js` is `/home/me/cwl/user_guide/hello.js` outside the container but `/var/lib/cwl/job369354770_examples/hello.js` inside @@ -111,4 +109,5 @@ the container, as reflected in the invocation of the `node` command. [docker]: https://docker.io -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/08-arguments.md b/08-arguments/index.md similarity index 91% rename from _episodes/08-arguments.md rename to 08-arguments/index.md index 4a35b5ad..091451a0 100644 --- a/_episodes/08-arguments.md +++ b/08-arguments/index.md @@ -1,5 +1,4 @@ --- -title: "Additional Arguments and Parameters" teaching: 10 exercises: 0 questions: @@ -15,6 +14,9 @@ correspond exactly to input parameters." is actually executed." - "Runtime parameters are referred under the `runtime` namespace." --- + +# Additional Arguments and Parameters + Sometimes tools require additional command line options that don't correspond exactly to input parameters. @@ -27,17 +29,16 @@ instead. *arguments.cwl* -~~~ -{% include cwl/08-arguments/arguments.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/08-arguments/arguments.cwl +:language: yaml +``` + *arguments-job.yml* -~~~ -{% include cwl/08-arguments/arguments-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/08-arguments/arguments-job.yml +:language: yaml +``` Now create a sample Java file and invoke `cwl-runner` providing the tool wrapper and the input object on the command line: @@ -73,7 +74,6 @@ Final process status is success } ~~~ -{: .output} Here we use the `arguments` field to add an additional argument to the command line that isn't tied to a specific input parameter. @@ -81,7 +81,6 @@ command line that isn't tied to a specific input parameter. ~~~ arguments: ["-d", $(runtime.outdir)] ~~~ -{: .source} This example references a runtime parameter. Runtime parameters provide information about the hardware or software environment when the tool is @@ -92,4 +91,5 @@ designated output directory. Other parameters include `$(runtime.tmpdir)`, CWL specification for details. [runtime]: https://www.commonwl.org/v1.0/CommandLineTool.html#Runtime_environment -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/09-array-inputs.md b/09-array-inputs/index.md similarity index 88% rename from _episodes/09-array-inputs.md rename to 09-array-inputs/index.md index 96626cb4..18e7943e 100644 --- a/_episodes/09-array-inputs.md +++ b/09-array-inputs/index.md @@ -1,5 +1,4 @@ --- -title: "Array Inputs" teaching: 10 exercises: 0 questions: @@ -16,6 +15,9 @@ with the `inputBinding` field is provided in the description." - "Use the `itemSeparator` field to control concatenatation of array parameters." --- + +# Array Inputs + It is easy to add arrays of input parameters represented to the command line. There are two ways to specify an array parameter. First is to provide `type` field with `type: array` and `items` defining the valid data types @@ -24,17 +26,15 @@ the type name to indicate that input parameter is array of that type. *array-inputs.cwl* -~~~ -{% include cwl/09-array-inputs/array-inputs.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/09-array-inputs/array-inputs.cwl +:language: yaml +``` *array-inputs-job.yml* -~~~ -{% include cwl/09-array-inputs/array-inputs-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/09-array-inputs/array-inputs-job.yml +:language: yaml +``` Now invoke `cwl-runner` providing the tool wrapper and the input object on the command line: @@ -65,7 +65,6 @@ Final process status is success $ cat output.txt -A one two three -B=four -B=five -B=six -C=seven,eight,nine ~~~ -{: .output} The `inputBinding` can appear either on the outer array parameter definition or the inner array element definition, and these produce different behavior when @@ -77,7 +76,8 @@ separator string. Note that the arrays of inputs are specified inside square brackets `[]` in `array-inputs-job.yml`. Arrays can also be expressed over multiple lines, where array values that are not defined with an associated key are marked by a leading `-`. This will be demonstrated in the next lesson -and is discussed in more detail in the [YAML Guide]({{ page.root }}{% link _extras/yaml.md %}#arrays). +and is discussed in more detail in the [YAML Guide](../yaml/index.md#arrays). You can specify arrays of arrays, arrays of records, and other complex types. -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/10-array-outputs.md b/10-array-outputs/index.md similarity index 81% rename from _episodes/10-array-outputs.md rename to 10-array-outputs/index.md index 678c2343..6a2b66a3 100644 --- a/_episodes/10-array-outputs.md +++ b/10-array-outputs/index.md @@ -1,5 +1,4 @@ --- -title: "Array Outputs" teaching: 10 exercises: 0 questions: @@ -12,21 +11,22 @@ keypoints: - "Use wildcards and filenames to specify the output files that will be returned after tool execution." --- + +# Array Outputs + You can also capture multiple output files into an array of files using `glob`. *array-outputs.cwl* -~~~ -{% include cwl/10-array-outputs/array-outputs.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/10-array-outputs/array-outputs.cwl +:language: yaml +``` *array-outputs-job.yml* -~~~ -{% include cwl/10-array-outputs/array-outputs-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/10-array-outputs/array-outputs-job.yml +:language: yaml +``` Now invoke `cwl-runner` providing the tool wrapper and the input object on the command line: @@ -52,11 +52,11 @@ Final process status is success ] } ~~~ -{: .output} -As described in the [YAML Guide]({{ page.root }}{% link _extras/yaml.md %}#arrays), +As described in the [YAML Guide](../yaml/index.md#arrays), the array of expected outputs is specified in `array-outputs-job.yml` with each entry marked by a leading `-`. This format can also be used in CWL descriptions to mark entries in arrays, as demonstrated in several of the upcoming sections. -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/11-records.md b/11-records/index.md similarity index 86% rename from _episodes/11-records.md rename to 11-records/index.md index ccd6ba49..5fcd1471 100644 --- a/_episodes/11-records.md +++ b/11-records/index.md @@ -1,5 +1,4 @@ --- -title: "Advanced Inputs" teaching: 10 exercises: 0 questions: @@ -11,6 +10,9 @@ keypoints: - "Multiple `record`s within the same parameter description are treated as exclusive." --- + +# Advanced Inputs + Sometimes an underlying tool has several arguments that must be provided together (they are dependent) or several arguments that cannot be provided together (they are exclusive). You can use records and type unions to group @@ -18,17 +20,15 @@ parameters together to describe these two conditions. *record.cwl* -~~~ -{% include cwl/11-records/record.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/11-records/record.cwl +:language: yaml +``` *record-job1.yml* -~~~ -{% include cwl/11-records/record-job1.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/11-records/record-job1.yml +:language: yaml +``` ~~~ $ cwl-runner record.cwl record-job1.yml @@ -37,16 +37,14 @@ Invalid job input record: record-job1.yml:1:1: the `dependent_parameters` field is not valid because missing required field `itemB` ~~~ -{: .output} In the first example, you can't provide `itemA` without also providing `itemB`. *record-job2.yml* -~~~ -{% include cwl/11-records/record-job2.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/11-records/record-job2.yml +:language: yaml +``` ~~~ $ cwl-runner record.cwl record-job2.yml @@ -73,17 +71,15 @@ Final process status is success $ cat output.txt -A one -B two -C three ~~~ -{: .output} In the second example, `itemC` and `itemD` are exclusive, so only `itemC` is added to the command line and `itemD` is ignored. *record-job3.yml* -~~~ -{% include cwl/11-records/record-job3.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/11-records/record-job3.yml +:language: yaml +``` ~~~ $ cwl-runner record.cwl record-job3.yml @@ -109,9 +105,9 @@ Final process status is success $ cat output.txt -A one -B two -D four ~~~ -{: .output} In the third example, only `itemD` is provided, so it appears on the command line. -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/12-env.md b/12-env/index.md similarity index 85% rename from _episodes/12-env.md rename to 12-env/index.md index 4b8c6c17..2942881f 100644 --- a/_episodes/12-env.md +++ b/12-env/index.md @@ -1,5 +1,4 @@ --- -title: "Environment Variables" teaching: 10 exercises: 0 questions: @@ -12,23 +11,24 @@ variables." - "Use the `EnvVarRequirement` field to set environment variables inside a tool's environment." --- + +# Environment Variables + Tools run in a restricted environment and do not inherit most environment variables from the parent process. You can set environment variables for the tool using `EnvVarRequirement`. *env.cwl* -~~~ -{% include cwl/12-env/env.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/12-env/env.cwl +:language: yaml +``` *echo-job.yml* -~~~ -{% include cwl/12-env/echo-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/12-env/echo-job.yml +:language: yaml +``` Now invoke `cwl-runner` with the tool wrapper and the input object on the command line: @@ -54,5 +54,5 @@ PATH=/bin:/usr/bin:/usr/local/bin HOME=/home/example TMPDIR=/tmp/tmp63Obpk ~~~ -{: .output} -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/13-expressions.md b/13-expressions/index.md similarity index 92% rename from _episodes/13-expressions.md rename to 13-expressions/index.md index bf169b59..b1e967e8 100644 --- a/_episodes/13-expressions.md +++ b/13-expressions/index.md @@ -1,5 +1,4 @@ --- -title: "JavaScript Expressions" teaching: 10 exercises: 0 questions: @@ -13,6 +12,9 @@ expressions that will be evaluated by the CWL runner." - "Expressions are only valid in certain fields." - "Expressions should only be used when no built in CWL solution exists." --- + +# JavaScript Expressions + If you need to manipulate input parameters, include the requirement `InlineJavascriptRequirement` and then anywhere a parameter reference is legal you can provide a fragment of Javascript that will be evaluated by @@ -26,20 +28,18 @@ See the [list of recommended practices][rec-practices].__ *expression.cwl* -~~~ -{% include cwl/13-expressions/expression.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/13-expressions/expression.cwl +:language: yaml +``` As this tool does not require any `inputs` we can run it with an (almost) empty job file: *empty.yml* -~~~ -{% include cwl/13-expressions/empty.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/13-expressions/empty.yml +:language: yaml +``` `empty.yml` contains a description of an empty JSON object. JSON objects descriptions are contained inside curly brackets `{}`, so an empty object is @@ -80,7 +80,6 @@ Final process status is success $ cat output.txt -A 2 -B baz -C 10 9 8 7 6 5 4 3 2 1 ~~~ -{: .output} Note that requirements can be provided with the map syntax, as in the example above: @@ -88,21 +87,20 @@ Note that requirements can be provided with the map syntax, as in the example ab requirements: InlineJavascriptRequirement: {} ~~~ -{: .source} -Or as an array, with each entry (in this case, only `class: InlineJavascriptRequirement`) marked by a `-`. +Or as an array, with each entry (in this case, only `class: InlineJavascriptRequirement`) marked by a `-`. The same syntax is used to describe the additional command line arguments. ~~~ requirements: - class: InlineJavascriptRequirement ~~~ -{: .source} +``` > ## Where are JavaScript expressions allowed? -> Just like [parameter references]({{ page.root }}{% link _episodes/06-params.md %}), you can use JavaScript Expressions +> Just like [parameter references](/_episodes/06-params.md), you can use JavaScript Expressions > only in certain fields. These are: -> +> > - From [`CommandLineTool`](https://www.commonwl.org/v1.0/CommandLineTool.html#CommandLineTool) > - `arguments` > - `valueFrom` @@ -149,9 +147,10 @@ requirements: > - From `EnvVarRequirement` > - From [EnvironmentDef](https://www.commonwl.org/v1.0/CommandLineTool.html#EnvironmentDef) > - `envValue` -{: .callout } +``` [file-prop]: https://www.commonwl.org/v1.0/CommandLineTool.html#File [rec-practices]: https://www.commonwl.org/user_guide/rec-practices/ -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/14-runtime.md b/14-runtime/index.md similarity index 88% rename from _episodes/14-runtime.md rename to 14-runtime/index.md index 32d17f6a..66745ba5 100644 --- a/_episodes/14-runtime.md +++ b/14-runtime/index.md @@ -1,5 +1,4 @@ --- -title: "Creating Files at Runtime" teaching: 10 exercises: 0 questions: @@ -13,6 +12,9 @@ keypoints: - "Use `InitialWorkDirRequirement` to specify input files that need to be created during tool runtime." --- + +# Creating Files at Runtime + Sometimes you need to create a file on the fly from input parameters, such as tools which expect to read their input configuration from a file rather than the command line parameters, or need a small wrapper shell script. @@ -21,31 +23,29 @@ To generate such files we can use the `InitialWorkDirRequirement`. *createfile.cwl* -~~~ -{% include cwl/14-runtime/createfile.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/14-runtime/createfile.cwl +:language: yaml +``` -Any [expressions](../13-expressions/index.html) like `$(inputs.message)` are +Any [expressions](/13-expressions/index.md) like `$(inputs.message)` are expanded by the CWL engine before creating the file; here inserting the value at the input `message`. -> ## Tip +```{tip} > The _CWL expressions_ are independent of any _shell variables_ used later during command line tool invocation. That means that any genuine need for the character `$` must be **escaped** with `\`, for instance `\${PREFIX}` above is expanded to `${PREFIX}` in the generated file to be evaluated by the shell script instead of the CWL engine. -{: .callout} +``` To test the above CWL tool use this job to provide the input value `message`: *echo-job.yml* -~~~ -{% include cwl/14-runtime/echo-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/14-runtime/echo-job.yml +:language: yaml +``` Before we run this, lets look at each step in a little more detail. The base command `baseCommand: ["sh", "example.sh"]` @@ -60,7 +60,7 @@ but it must match what was specified in the `baseCommand`. The final part is `entry:`, this is followed by `|-` which is YAML quoting syntax, and means that you are using a multiline string (without it we would need to write the whole script on one line). -(see the [YAML Guide]({{ page.root }}{% link _extras/yaml.md %}#maps) +(see the [YAML Guide](../yaml/index.md#maps) for more about the formating) Now invoke `cwl-runner` with the tool wrapper and the input object on the @@ -86,8 +86,6 @@ Final process status is success $ cat output.txt Message is: Hello world! ~~~ -{: .output} - - -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/15-staging.md b/15-staging/index.md similarity index 87% rename from _episodes/15-staging.md rename to 15-staging/index.md index ae089987..aacb7bd3 100644 --- a/_episodes/15-staging.md +++ b/15-staging/index.md @@ -1,5 +1,4 @@ --- -title: "Staging Input Files" teaching: 10 exercises: 0 questions: @@ -12,6 +11,9 @@ keypoints: - "Use `InitialWorkDirRequirement` to stage input files in the working directory." --- + +# Staging Input Files + Normally, input files are located in a read-only directory separate from the output directory. This causes problems if the underlying tool expects to write its output files alongside the input file in the same directory. You use `InitialWorkDirRequirement` to stage input files into the output directory. @@ -20,17 +22,15 @@ input file from its leading directory path. *linkfile.cwl* -~~~ -{% include cwl/15-staging/linkfile.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/15-staging/linkfile.cwl +:language: yaml +``` *arguments-job.yml* -~~~ -{% include cwl/15-staging/arguments-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/15-staging/arguments-job.yml +:language: yaml +``` Now invoke `cwl-runner` with the tool wrapper and the input object on the command line: @@ -48,5 +48,5 @@ Final process status is success } } ~~~ -{: .output} -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/16-file-formats.md b/16-file-formats/index.md similarity index 92% rename from _episodes/16-file-formats.md rename to 16-file-formats/index.md index 9bb0f6d1..08addb70 100644 --- a/_episodes/16-file-formats.md +++ b/16-file-formats/index.md @@ -1,5 +1,4 @@ --- -title: "File Formats" teaching: 10 exercises: 0 questions: @@ -12,6 +11,9 @@ keypoints: - "Once your tool is mature, we recommend specifying formats by referencing existing ontologies e.g. EDAM." --- + +# File Formats + Tools and workflows can take `File` types as input and produce them as output. We also recommend indicating the format for `File` types. This helps document for others how to use your tool while allowing you to do some simple @@ -31,16 +33,15 @@ formats and warn you if there seem to be some obvious mismatches. *metadata_example.cwl* -~~~ -{% include cwl/16-file-formats/metadata_example.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/16-file-formats/metadata_example.cwl +:language: yaml +``` The equivalent of this CWL description in command line format is: `wc -l /path/to/aligned_sequences.ext > output.txt` -#### Sample Parameter Files +## Sample Parameter Files Below is an example of a parameter file for the example above. We encourage checking in working examples of parameter files for your tool. This allows @@ -49,10 +50,9 @@ parameterization. *sample.yml* -~~~ -{% include cwl/16-file-formats/sample.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/16-file-formats/sample.yml +:language: yaml +``` ___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/gh-pages/_includes/cwl/16-file-formats/file-formats.bam ](https://github.com/common-workflow-language/user_guide/raw/gh-pages/_includes/cwl/16-file-formats/file-formats.bam) and can be downloaded e.g. via `wget`: @@ -60,8 +60,6 @@ ___Note:___ To follow the example below, you need to download the example input ~~~ wget https://github.com/common-workflow-language/user_guide/raw/gh-pages/_includes/cwl/16-file-formats/file-formats.bam ~~~ -{: .source} - Now invoke `cwl-runner` with the tool wrapper and the input object on the command line: @@ -86,8 +84,8 @@ Final process status is success } } ~~~ -{: .output} [IANA]: https://www.iana.org/assignments/media-types/media-types.xhtml [EDAM]: https://www.ebi.ac.uk/ols/ontologies/edam/terms?iri=http%3A%2F%2Fedamontology.org%2Fformat_1915 -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/17-metadata.md b/17-metadata/index.md similarity index 86% rename from _episodes/17-metadata.md rename to 17-metadata/index.md index 997b5e1e..28a3e556 100644 --- a/_episodes/17-metadata.md +++ b/17-metadata/index.md @@ -1,5 +1,4 @@ --- -title: "Metadata and Authorship" teaching: 10 exercises: 0 questions: @@ -12,6 +11,9 @@ keypoints: - "Developers should provide a minimal amount of authorship information to encourage correct citation." --- + +# Metadata and Authorship + Implementation extensions not required for correct execution (for example, fields related to GUI presentation) and metadata about the tool or workflow itself (for example, authorship for use in citations) may be provided as @@ -27,16 +29,15 @@ and workflows. This example includes metadata allowing others to cite your tool. *metadata_example2.cwl* -~~~ -{% include cwl/17-metadata/metadata_example2.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/17-metadata/metadata_example2.cwl +:language: yaml +``` The equivalent of this CWL description in command line format is: `wc -l /path/to/aligned_sequences.ext > output.txt` -#### Extended Example +## Extended Example For those that are highly motivated, it is also possible to annotate your tool with a much larger amount of metadata. This example includes EDAM ontology tags @@ -45,10 +46,10 @@ requirements in order to use the tool, and a few more metadata fields. *metadata_example3.cwl* -~~~ -{% include cwl/17-metadata/metadata_example3.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/17-metadata/metadata_example3.cwl +:language: yaml +``` [schema-salad]: https://www.commonwl.org/v1.0/SchemaSalad.html#Explicit_context -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/19-custom-types.md b/19-custom-types/index.md similarity index 89% rename from _episodes/19-custom-types.md rename to 19-custom-types/index.md index e024a92c..91326c09 100644 --- a/_episodes/19-custom-types.md +++ b/19-custom-types/index.md @@ -1,5 +1,4 @@ --- -title: "Custom Types" teaching: 10 exercises: 0 questions: @@ -14,6 +13,8 @@ keypoints: - "Custom types are described in separate YAML files and imported as needed." --- +# Custom Types + Sometimes you may want to write your own custom types for use and reuse in CWL descriptions. Use of such custom types can reduce redundancy between multiple descriptions that all use the same type, and also allow for additional @@ -25,24 +26,21 @@ converting a standard biom table file to hd5 format. *custom-types.cwl* -~~~ -{% include cwl/19-custom-types/custom-types.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/19-custom-types/custom-types.cwl +:language: yaml +``` *custom-types.yml* -~~~ -{% include cwl/19-custom-types/custom-types.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/19-custom-types/custom-types.yml +:language: yaml +``` ___Note:___ To follow the example below, you need to download the example input file, *rich_sparse_otu_table.biom*. The file is available from [https://raw.githubusercontent.com/common-workflow-language/user_guide/gh-pages/_includes/cwl/19-custom-types/rich_sparse_otu_table.biom](https://raw.githubusercontent.com/common-workflow-language/user_guide/gh-pages/_includes/cwl/19-custom-types/rich_sparse_otu_table.biom) and can be downloaded e.g. via `wget`: ~~~ wget https://raw.githubusercontent.com/common-workflow-language/user_guide/gh-pages/_includes/cwl/19-custom-types/rich_sparse_otu_table.biom ~~~ -{: .source} On line 29, in `inputs:table_type`, a list of allowable table options to be used in the table conversion are imported as a custom object: @@ -59,21 +57,19 @@ inputs: inputBinding: prefix: --table-type ``` -{: .source} The reference to a custom type is a combination of the name of the file in which the object is defined (`biom-convert-table.yaml`) and the name of the object within that file (`table_type`) that defines the custom type. In this case the `symbols` array from the imported `biom-convert-table.yaml` file define the allowable table options. -For example, in `custom-types.yml`, we pass `OTU table` as an `input` that -tells the tool to create an OTU table in hd5 format. +For example, in `custom-types.yml`, we pass `OTU table` as an `input` that +tells the tool to create an OTU table in hd5 format. The contents of the YAML file describing the custom type are given below: -~~~ -{% include cwl/19-custom-types/biom-convert-table.yaml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/19-custom-types/biom-convert-table.yaml +:language: yaml +``` In order for the custom type to be used in the CWL description, it must be imported. Imports are described in `requirements:SchemaDefRequirement`, as @@ -89,7 +85,6 @@ requirements: types: - $import: biom-convert-table.yaml ``` -{: .source} Note also that the author of this CWL description has also included `ResourceRequirement`s, specifying the minimum amount of RAM and number of cores @@ -98,4 +93,5 @@ the software that the description was written for and other useful metadata. These features are discussed further in other chapters of this user guide. [biom]: http://biom-format.org/ -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/20-software-requirements.md b/20-software-requirements/index.md similarity index 93% rename from _episodes/20-software-requirements.md rename to 20-software-requirements/index.md index 807ddd3e..a70d8d77 100644 --- a/_episodes/20-software-requirements.md +++ b/20-software-requirements/index.md @@ -1,5 +1,4 @@ --- -title: "Specifying Software Requirements" teaching: 10 exercises: 0 questions: @@ -12,16 +11,18 @@ that is required." keypoints: - "Software requirements should be specified under `hints:SoftwareRequirement`." --- + +# Specifying Software Requirements + Often tool descriptions will be written for a specific version of a software. To make it easier for others to use your descriptions, you can include a `SoftwareRequirement` field in the `hints` section. This may also help to avoid confusion about which version of a tool the description was written for. -~~~ -{% include cwl/20-software-requirements/custom-types.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/20-software-requirements/custom-types.cwl +:language: yaml +``` In this example, the software requirement being described is InterProScan version 5.21-60. @@ -34,7 +35,6 @@ hints: specs: [ "https://identifiers.org/rrid/RRID:SCR_005829" ] version: [ "5.21-60" ] ~~~ -{: .source} Depending on your CWL runner, these hints may be used to check that required software is installed and available before the job is run. To enable @@ -57,4 +57,5 @@ include the DOI for the main tool citation and the URL to the tool. [dependencies]: https://github.com/common-workflow-language/cwltool#leveraging-softwarerequirements-beta [identifiers]: https://identifiers.org/ [scicrunch-add-tool]: https://scicrunch.org/page/tutorials/336 -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/21-1st-workflow.md b/21-1st-workflow/index.md similarity index 91% rename from _episodes/21-1st-workflow.md rename to 21-1st-workflow/index.md index a633e727..9d7f4803 100644 --- a/_episodes/21-1st-workflow.md +++ b/21-1st-workflow/index.md @@ -1,5 +1,4 @@ --- -title: "Writing Workflows" teaching: 10 exercises: 0 questions: @@ -13,28 +12,30 @@ and `outputs` fields respectively." - "The steps are specified under `steps`." - "Execution order is determined by the connections between steps." --- + +# Writing Workflows + This workflow extracts a java source file from a tar file and then compiles it. *1st-workflow.cwl* -~~~ -{% include cwl/21-1st-workflow/1st-workflow.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/21-1st-workflow/1st-workflow.cwl +:language: yaml +``` +``` > ## Visualization of 1st-workflow.cwl > Visualization of 1st-workflow.cwl -{: .callout} +``` Use a YAML or a JSON object in a separate file to describe the input of a run: *1st-workflow-job.yml* -~~~ -{% include cwl/21-1st-workflow/1st-workflow-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/21-1st-workflow/1st-workflow-job.yml +:language: yaml +``` Now invoke `cwl-runner` with the tool wrapper and the input object on the command line: @@ -57,7 +58,6 @@ Final process status is success } } ~~~ -{: .output} What's going on here? Let's break it down: @@ -65,7 +65,6 @@ What's going on here? Let's break it down: cwlVersion: v1.0 class: Workflow ~~~ -{: .source} The `cwlVersion` field indicates the version of the CWL spec used by the document. The `class` field indicates this document describes a workflow. @@ -76,7 +75,6 @@ inputs: tarball: File name_of_file_to_extract: string ~~~ -{: .source} The `inputs` section describes the inputs of the workflow. This is a list of input parameters where each parameter consists of an identifier @@ -89,7 +87,6 @@ outputs: type: File outputSource: compile/classfile ~~~ -{: .source} The `outputs` section describes the outputs of the workflow. This is a list of output parameters where each parameter consists of an identifier @@ -105,7 +102,6 @@ steps: extractfile: name_of_file_to_extract out: [extracted_file] ~~~ -{: .source} The `steps` section describes the actual steps of the workflow. In this example, the first step extracts a file from a tar file, and the second @@ -116,7 +112,7 @@ instead the order is determined by the dependencies between steps (using another may run in parallel. The first step, `untar` runs `tar-param.cwl` (described previously in -[Parameter References]({{ page.root }}{% link _episodes/06-params.md %})). +[Parameter References](/06-params/index.md)). This tool has two input parameters, `tarfile` and `extractfile` and one output parameter `extracted_file`. @@ -136,13 +132,13 @@ expected from the tool. src: untar/extracted_file out: [classfile] ~~~ -{: .source} The second step `compile` depends on the results from the first step by connecting the input parameter `src` to the output parameter of `untar` using `untar/extracted_file`. It runs `arguments.cwl` (described previously in -[Additional Arguments and Parameters]({{ page.root }}{% link _episodes/08-arguments.md %})). +[Additional Arguments and Parameters](/08-arguments/index.md)). The output of this step `classfile` is connected to the `outputs` section for the Workflow, described above. -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/22-nested-workflows.md b/22-nested-workflows/index.md similarity index 94% rename from _episodes/22-nested-workflows.md rename to 22-nested-workflows/index.md index b461003a..3443f91e 100644 --- a/_episodes/22-nested-workflows.md +++ b/22-nested-workflows/index.md @@ -1,5 +1,4 @@ --- -title: "Nested Workflows" teaching: 10 exercises: 0 questions: @@ -16,41 +15,42 @@ file provided as the value to the `run` field." overwritten by a value in the input object." - "Use `>` to ignore newlines in long commands split over multiple lines." --- + +# Nested Workflows + Workflows are ways to combine multiple tools to perform a larger operations. We can also think of a workflow as being a tool itself; a CWL workflow can be used as a step in another CWL workflow, if the workflow engine supports the `SubworkflowFeatureRequirement`: - ~~~ requirements: SubworkflowFeatureRequirement: {} ~~~ -{: .source} Here's an example workflow that uses our `1st-workflow.cwl` as a nested workflow: *nestedworkflows.cwl* -~~~ -{% include cwl/22-nested-workflows/nestedworkflows.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/22-nested-workflows/nestedworkflows.cwl +:language: yaml +``` -> ## Visualization of the workflow and the inner workflow from its `compile` step +```{note} +>

Visualization of the workflow and the inner workflow from its `compile` step

> This two-step workflow starts with the `create-tar` step which is connected to > the `compile` step in orange; `compile` is another workflow, diagrammed on the > right. In purple we see the fixed string `"Hello.java"` being supplied as the > `name_of_file_to_extract`. -> +> > Visualization of nestedworkflows.cwl > Visualization of 1st-workflow.cwl -{: .callout} +``` A CWL `Workflow` can be used as a `step` just like a `CommandLineTool`, its CWL file is included with `run`. The workflow inputs (`tarball` and `name_of_file_to_extract`) and outputs @@ -65,7 +65,6 @@ file is included with `run`. The workflow inputs (`tarball` and `name_of_file_to default: "Hello.java" out: [compiled_class] ~~~ -{: .source} Our `1st-workflow.cwl` was parameterized with workflow inputs, so when running it we had to provide a job file to denote the tar file and `*.java` filename. @@ -96,7 +95,6 @@ requirement, before adding it to a tar file. } } ~~~ -{: .source} In this case our step can assume `Hello.java` rather than be parameterized, so we can use hardcoded values `hello.tar` and `Hello.java` in a `baseCommand` and @@ -114,7 +112,6 @@ the resulting `outputs`: outputBinding: glob: "hello.tar" ~~~ -{: .source} Did you notice that we didn't split out the `tar --create` tool to a separate file, but rather embedded it within the CWL Workflow file? This is generally not best @@ -131,4 +128,5 @@ Nested workflows can be a powerful feature to generate higher-level functional and reusable workflow units - but just like for creating a CWL Tool description, care must be taken to improve its usability in multiple workflows. -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/23-scatter-workflow.md b/23-scatter-workflow/index.md similarity index 87% rename from _episodes/23-scatter-workflow.md rename to 23-scatter-workflow/index.md index bea0ba75..e6be4a5c 100644 --- a/_episodes/23-scatter-workflow.md +++ b/23-scatter-workflow/index.md @@ -1,5 +1,4 @@ --- -title: "Scattering Workflows" teaching: 10 exercises: 0 questions: @@ -13,6 +12,9 @@ supports the `ScatterFeatureRequirement`." - The `scatter` field references the step level inputs, not the workflow inputs - Scatter runs on each step specified independently --- + +# Scattering Workflows + Now that we know how to write workflows, we can start utilizing the `ScatterFeatureRequirement`. This feature tells the runner that you wish to run a tool or workflow multiple times over a list of inputs. The workflow then takes the input(s) as an array and will run the specified step(s) @@ -23,7 +25,6 @@ on multiple inputs without having to generate many different commands or input y requirements: ScatterFeatureRequirement: {} ~~~ -{: .source} The most common reason a new user might want to use scatter is to perform the same analysis on different samples. Let's start with a simple workflow that calls our first example and takes @@ -31,10 +32,9 @@ an array of strings as input to the workflow: *scatter-workflow.cwl* -~~~ -{% include cwl/23-scatter-workflow/scatter-workflow.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/23-scatter-workflow/scatter-workflow.cwl +:language: yaml +``` Aside from the `requirements` section including `ScatterFeatureRequirement`, what is going on here? @@ -43,7 +43,6 @@ going on here? inputs: message_array: string[] ~~~ -{: .source} First of all, notice that the main workflow level input here requires an array of strings. @@ -56,7 +55,6 @@ steps: message: message_array out: [] ~~~ -{: .source} Here we've added a new field to the step `echo` called `scatter`. This field tells the runner that we'd like to scatter over this input for this particular step. Note that @@ -71,10 +69,9 @@ Using the following input file: *scatter-job.yml* -~~~ -{% include cwl/23-scatter-workflow/scatter-job.yml %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/23-scatter-workflow/scatter-job.yml +:language: yaml +``` As a reminder, `1st-tool.cwl` simply calls the command `echo` on a message. If we invoke `cwl-runner scatter-workflow.cwl scatter-job.yml` on the command line: @@ -106,10 +103,9 @@ Hallo welt! [workflow scatter-workflow.cwl] completed success {} Final process status is success -~~~ -{: .output} +~~~ -You can see that the workflow calls echo multiple times on each element of our +You can see that the workflow calls echo multiple times on each element of our `message_array`. Ok, so how about if we want to scatter over two steps in a workflow? Let's perform a simple echo like above, but capturing `stdout` by adding the following @@ -122,26 +118,23 @@ outputs: echo_out: type: stdout ~~~ -{: .source} And add a second step that uses `wc` to count the characters in each file. See the tool below: *wc-tool.cwl* -~~~ -{% include cwl/23-scatter-workflow/wc-tool.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/23-scatter-workflow/wc-tool.cwl +:language: yaml +``` Now, how do we incorporate scatter? Remember the scatter field is under each step: *scatter-two-steps.cwl* -~~~ -{% include cwl/23-scatter-workflow/scatter-two-steps.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/23-scatter-workflow/scatter-two-steps.cwl +:language: yaml +``` Here we have placed the scatter field under each step. This is fine for this example since it runs quickly, but if you're running many samples for a more complex workflow, you may @@ -153,20 +146,20 @@ Pretend that `echo Hello World!` takes 1 minute to perform, `wc -c` on the outpu and that `echo Hallo welt!` takes 5 minutes to perform, and `wc` on that output takes 3 minutes. Even though `echo Hello World!` could finish in 4 minutes, it will actually finish in 8 minutes because the first step must wait on `echo Hallo welt!`. You can see how this might not scale -well. +well. Ok, so how do we scatter on steps that can proceed independent of other samples? Remember from -[chapter 21]({{ page.root }}/22-nested-workflows/), that we can make an entire workflow a single step in another workflow! Convert our +[chapter 21](/22-nested-workflows/index.md), that we can make an entire workflow a single step in another workflow! Convert our two step workflow to a single step subworkflow: *scatter-nested-workflow.cwl* -~~~ -{% include cwl/23-scatter-workflow/scatter-nested-workflow.cwl %} -~~~ -{: .source} +```{literalinclude} /_includes/cwl/23-scatter-workflow/scatter-nested-workflow.cwl +:language: yaml +``` Now the scatter acts on a single step, but that step consists of two steps so each step is performed in parallel. -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/_episodes/24_conditional-workflow.md b/24_conditional-workflow/index.md similarity index 96% rename from _episodes/24_conditional-workflow.md rename to 24_conditional-workflow/index.md index a5373b20..454dc7af 100644 --- a/_episodes/24_conditional-workflow.md +++ b/24_conditional-workflow/index.md @@ -1,5 +1,4 @@ --- -title: "Conditional workflows" teaching: 24 exercises: 0 questions: @@ -9,7 +8,10 @@ objectives: keypoints: - "" --- -This workflow contains a conditional step and is executed based on the input. + +# Conditional workflows + +This workflow contains a conditional step and is executed based on the input. This allows workflows to skip additional steps based on input parameters given at the start of the program or by previous steps. *conditional-workflow.cwl* @@ -58,7 +60,7 @@ class: Workflow cwlVersion: v1.2 ``` -The first step of the worklfow (step1) contains two input properties and will execute foo.cwl when the conditions are met. The new property `when` is where the condition validation takes place. In this case only when `in1` from the workflow contains a value `< 1` this step will be executed. +The first step of the worklfow (step1) contains two input properties and will execute foo.cwl when the conditions are met. The new property `when` is where the condition validation takes place. In this case only when `in1` from the workflow contains a value `< 1` this step will be executed. ``` steps: @@ -92,7 +94,7 @@ INFO [workflow ] completed success INFO Final process status is success ``` -When a value of 3 is given the first conditional step will not be executed but the second step will `cwltool cond-wf-003.1.cwl --val 3`. +When a value of 3 is given the first conditional step will not be executed but the second step will `cwltool cond-wf-003.1.cwl --val 3`. ``` INFO [workflow ] start @@ -129,4 +131,5 @@ INFO [workflow ] completed permanentFail WARNING Final process status is permanentFail ``` -{% include links.md %} +```{include} ../_includes/links.md +``` diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index c0ac4141..6948d0b6 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,7 +1,5 @@ ---- -layout: page -title: "Contributor Code of Conduct" ---- +# Code of Conduct + As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, @@ -21,4 +19,5 @@ these spaces at the discretion of the leadership team. For more details, see the [complete CWL project code of conduct](https://github.com/common-workflow-language/common-workflow-language/blob/master/CODE_OF_CONDUCT.md). -{% include links.md %} +```{include} /_includes/links.md +``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fcfbc294..cddaec8e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -The [Common Workflow Language project](cwl-site) is an open source project, +The [Common Workflow Language project][cwl-site] is an open source project, and we welcome contributions of all kinds: new lessons, fixes to existing material, @@ -10,12 +10,12 @@ and reviews of proposed changes are all welcome. ## Contributor Agreement By contributing, -you agree that we may redistribute your work under [our license](LICENSE.md). +you agree that we may redistribute your work under [our license](/LICENSE.md). In exchange, we will address your issues and/or assess your change proposal as promptly as we can, and help you become a member of our community. -Everyone involved in the [Common Workflow Language project](cwl-site) -agrees to abide by our [code of conduct](CONDUCT.md). +Everyone involved in the [Common Workflow Language project][cwl-site] +agrees to abide by our [code of conduct](/CODE_OF_CONDUCT.md). ## How to Contribute @@ -41,7 +41,7 @@ and to meet some of our community members. 3. If you are comfortable with Git, and would like to add or change material, you can submit a pull request (PR). - Instructions for doing this are [included below](#using-github). + Instructions for doing this are [included below][#using-github]. ## Where to Contribute @@ -73,7 +73,7 @@ and submitting [bug reports][issues] about things that don't work, aren't clear, or are missing. If you are looking for ideas, please see [the list of issues for this repository][issues], -or the issues for [Common Workflow Language](cwl-issues) project itself. +or the issues for [Common Workflow Language][cwl-issues] project itself. Comments on issues and reviews of pull requests are just as welcome: we are smarter together than we are on our own. @@ -128,7 +128,7 @@ repository for reference while revising. ## Other Resources -General discussion of [Common Workflow Language](cwl-site) project +General discussion of [Common Workflow Language][cwl-site] project happens on the [discussion mailing list][discuss-list], which everyone is welcome to join. diff --git a/LICENSE.md b/LICENSE.md index bb048824..b5b69d3c 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,8 +1,5 @@ ---- -layout: page -title: "Licenses" -root: . ---- +# Licenses + ## Instructional Material This material is derived from a framework created by the Software Carpentry diff --git a/Makefile b/Makefile index d291abe6..3f77c588 100644 --- a/Makefile +++ b/Makefile @@ -1,121 +1,30 @@ -## ======================================== -## Commands for both workshop and lesson websites. - -# Settings -MAKEFILES=Makefile $(wildcard *.mk) -JEKYLL=jekyll -JEKYLL_VERSION=3.8.5 -PARSER=bin/markdown_ast.rb -DST=_site - -# Controls -.PHONY : commands clean files -.NOTPARALLEL: -all : commands - -## commands : show all commands. -commands : - @grep -h -E '^##' ${MAKEFILES} | sed -e 's/## //g' - -## docker-serve : use docker to build the site -docker-serve : - docker run --rm -it -v ${PWD}:/srv/jekyll -p 127.0.0.1:4000:4000 jekyll/jekyll:${JEKYLL_VERSION} make serve - -## serve : run a local server. -serve : lesson-md - ${JEKYLL} serve - -## site : build files but do not run a server. -site : lesson-md - ${JEKYLL} build - -# repo-check : check repository settings. -repo-check : - @bin/repo_check.py -s . - -## clean : clean up junk files. -clean : - @rm -rf ${DST} - @rm -rf .sass-cache - @rm -rf bin/__pycache__ - @find . -name .DS_Store -exec rm {} \; - @find . -name '*~' -exec rm {} \; - @find . -name '*.pyc' -exec rm {} \; - -## clean-rmd : clean intermediate R files (that need to be committed to the repo). -clean-rmd : - @rm -rf ${RMD_DST} - @rm -rf fig/rmd-* - -## ---------------------------------------- -## Commands specific to workshop websites. - -.PHONY : workshop-check - -## workshop-check : check workshop homepage. -workshop-check : - @bin/workshop_check.py . - -## ---------------------------------------- -## Commands specific to lesson websites. - -.PHONY : lesson-check lesson-md lesson-files lesson-fixme - -# RMarkdown files -RMD_SRC = $(wildcard _episodes_rmd/??-*.Rmd) -RMD_DST = $(patsubst _episodes_rmd/%.Rmd,_episodes/%.md,$(RMD_SRC)) - -# Lesson source files in the order they appear in the navigation menu. -MARKDOWN_SRC = \ - index.md \ - CODE_OF_CONDUCT.md \ - setup.md \ - $(sort $(wildcard _episodes/*.md)) \ - reference.md \ - $(sort $(wildcard _extras/*.md)) \ - LICENSE.md - -# Generated lesson files in the order they appear in the navigation menu. -HTML_DST = \ - ${DST}/index.html \ - ${DST}/conduct/index.html \ - ${DST}/setup/index.html \ - $(patsubst _episodes/%.md,${DST}/%/index.html,$(sort $(wildcard _episodes/*.md))) \ - ${DST}/reference/index.html \ - $(patsubst _extras/%.md,${DST}/%/index.html,$(sort $(wildcard _extras/*.md))) \ - ${DST}/license/index.html - -## lesson-md : convert Rmarkdown files to markdown -lesson-md : ${RMD_DST} - -_episodes/%.md: _episodes_rmd/%.Rmd - @bin/knit_lessons.sh $< $@ - -## lesson-check : validate lesson Markdown. -lesson-check : lesson-fixme - @bin/lesson_check.py -s . -p ${PARSER} -r _includes/links.md - -## lesson-check-all : validate lesson Markdown, checking line lengths and trailing whitespace. -lesson-check-all : - @bin/lesson_check.py -s . -p ${PARSER} -r _includes/links.md -l -w --permissive - -## unittest : run unit tests on checking tools. -unittest : - @bin/test_lesson_check.py - -## lesson-files : show expected names of generated files for debugging. -lesson-files : - @echo 'RMD_SRC:' ${RMD_SRC} - @echo 'RMD_DST:' ${RMD_DST} - @echo 'MARKDOWN_SRC:' ${MARKDOWN_SRC} - @echo 'HTML_DST:' ${HTML_DST} - -## lesson-fixme : show FIXME markers embedded in source files. -lesson-fixme : - @fgrep -i -n FIXME ${MARKDOWN_SRC} || true - -#------------------------------------------------------------------------------- -# Include extra commands if available. -#------------------------------------------------------------------------------- - --include commands.mk +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS = "-W" +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +watch: + @echo + @echo "Building and watching for changes in the documentation." + sphinx-autobuild --ignore venv . _build/html + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/README.md b/README.md index fb3c4dc2..0623aaed 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,9 @@ We'd like to ask you to familiarize yourself with our [Contribution Guide](CONTR the [more detailed guidelines][lesson-example] on proper formatting, ways to render the lesson locally, and even how to write new episodes. -- The text files for each tutorial can be found in the directory [_episodes](_episodes) +- The text files for each tutorial can be found in the directory [_episodes](/_episodes/index.md) -- The cwl and yaml code files linked to each tutorial can be found in the directory [_includes/cwl](_includes/cwl) +- The cwl and yaml code files linked to each tutorial can be found in the directory [_includes/cwl](https://github.com/common-workflow-language/user_guide/tree/gh-pages/_includes/cwl) This repo is based upon https://github.com/swcarpentry/styles and should be periodically resynced. diff --git a/_episodes/.gitkeep b/_episodes/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/_extras/.gitkeep b/_extras/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/_includes/aio-script.md b/_includes/aio-script.md index a81fbcdd..ddea41f1 100644 --- a/_includes/aio-script.md +++ b/_includes/aio-script.md @@ -1,10 +1,9 @@ -{% comment %} -As a maintainer, you don't need to edit this file. -If you notice that something doesn't work, please -open an issue: https://github.com/carpentries/styles/issues/new -{% endcomment %} +% As a maintainer, you don't need to edit this file. +% If you notice that something doesn't work, please +% open an issue: https://github.com/carpentries/styles/issues/new -{% include manual_episode_order.html %} +```{include} /_includes/manual_episode_order.html +``` -{% comment %} Create an anchor for every episode. {% endcomment %} +% Create an anchor for every episode. {% for lesson_episode in lesson_episodes %} {% if site.episode_order %} diff --git a/_includes/all_keypoints.html b/_includes/all_keypoints.html index f0abd251..2f7544e7 100644 --- a/_includes/all_keypoints.html +++ b/_includes/all_keypoints.html @@ -1,9 +1,9 @@ -{% comment %} - Display key points of all episodes for reference. -{% endcomment %} +% Display key points of all episodes for reference. -{% include base_path.html %} -{% include manual_episode_order.html %} +```{include} /_includes/base_path.html +``` +```{include} /_includes/manual_episode_order.html +```

Key Points

diff --git a/_includes/base_path.html b/_includes/base_path.html index 7efb3570..a9fd0cea 100644 --- a/_includes/base_path.html +++ b/_includes/base_path.html @@ -1,13 +1,11 @@ -{% comment %} -This is adapted from: https://ricostacruz.com/til/relative-paths-in-jekyll - -`page.url` gives the URL of the current page with a leading /: - -- when the URL ends with the extension (e.g., /foo/bar.html) then we can get - the depth by counting the number of / and remove - 1 -- when the URL ends with a / (e.g. /foo/bar/) then the number / gives the depth - directly -{% endcomment %} +% This is adapted from: https://ricostacruz.com/til/relative-paths-in-jekyll +% +% `page.url` gives the URL of the current page with a leading /: +% +% - when the URL ends with the extension (e.g., /foo/bar.html) then we can get +% the depth by counting the number of / and remove - 1 +% - when the URL ends with a / (e.g. /foo/bar/) then the number / gives the depth +% directly {% assign relative_root_path = '' %} diff --git a/_includes/carpentries.html b/_includes/carpentries.html index c032bd54..992553e9 100644 --- a/_includes/carpentries.html +++ b/_includes/carpentries.html @@ -1,8 +1,8 @@ -{% comment %} - General description of Software, Data, and Library Carpentry. -{% endcomment %} +% General description of Software, Data, and Library Carpentry. + +```{include} /_includes/base_path.html +``` -{% include base_path.html %}
@@ -12,7 +12,7 @@

The Carpentries comprises Software Carpentry, Data Carpentry, and Library Carpentry communities of Instructors, Trainers, Maintainers, helpers, and supporters who share a mission to teach - foundational coding and data science skills to researchers and people + foundational coding and data science skills to researchers and people working in library- and information-related roles. In January, 2018, The Carpentries was formed by the merger of Software Carpentry and Data Carpentry. Library Carpentry became an official Carpentries Lesson Program in November 2018.

diff --git a/_includes/episode_break.html b/_includes/episode_break.html index 36d2d2fa..3b51c46d 100644 --- a/_includes/episode_break.html +++ b/_includes/episode_break.html @@ -1,6 +1,4 @@ -{% comment %} - Display a break's timings in a box similar to a learning episode's. -{% endcomment %} +% Display a break's timings in a box similar to a learning episode's.

Overview

diff --git a/_includes/episode_keypoints.html b/_includes/episode_keypoints.html index 2baa53ef..5c20348c 100644 --- a/_includes/episode_keypoints.html +++ b/_includes/episode_keypoints.html @@ -1,6 +1,4 @@ -{% comment %} - Display key points for an episode. -{% endcomment %} +% Display key points for an episode.

Key Points

    diff --git a/_includes/episode_navbar.html b/_includes/episode_navbar.html index 5abf86f2..1bdf6107 100644 --- a/_includes/episode_navbar.html +++ b/_includes/episode_navbar.html @@ -1,19 +1,15 @@ -{% comment %} -For some reason, the relative_root_path seems out of scope in this file, so we -need to re-assign it here -{% endcomment %} +% For some reason, the relative_root_path seems out of scope in this file, so we +% need to re-assign it here -{% include base_path.html %} +```{include} /_includes/base_path.html +``` -{% comment %} - Navigation bar for an episode. -{% endcomment %} +% Navigation bar for an episode. -{% include manual_episode_order.html %} -{% comment %} - 'previous_episode' and 'next_episodes' are defined in 'manual_episode_order.html'. - These replace 'page.previous' and 'page.next' objects, correspondingly. -{% endcomment %} +```{include} /_includes/manual_episode_order.html +``` +% 'previous_episode' and 'next_episodes' are defined in 'manual_episode_order.html'. +% These replace 'page.previous' and 'page.next' objects, correspondingly.
    diff --git a/_includes/episode_overview.html b/_includes/episode_overview.html index cb87e0f6..7fc71a4f 100644 --- a/_includes/episode_overview.html +++ b/_includes/episode_overview.html @@ -1,6 +1,4 @@ -{% comment %} - Display an episode's timings and learning objectives. -{% endcomment %} +% Display an episode's timings and learning objectives.

    Overview

    diff --git a/_includes/gh_variables.html b/_includes/gh_variables.html index 3fdae4ac..eed3cc12 100644 --- a/_includes/gh_variables.html +++ b/_includes/gh_variables.html @@ -1,33 +1,23 @@ -{% comment %} -When rendering websites locally, `site.github.url` doesn't get resolved properly -unless a GitHub Personal Access Token is set up and available in the -environment. This leads to warnings and errors when trying to serve the site -locally. To work around this, we use the `jekyll.environment` variable which is -set to `development` when rendering the site locally, and set to `production` on -GitHub where `site.github.url` is defined. -{% endcomment %} +% When rendering websites locally, `site.github.url` doesn't get resolved properly +% unless a GitHub Personal Access Token is set up and available in the +% environment. This leads to warnings and errors when trying to serve the site +% locally. To work around this, we use the `jekyll.environment` variable which is +% set to `development` when rendering the site locally, and set to `production` on +% GitHub where `site.github.url` is defined. {% if jekyll.environment == "production" %} -{% comment %} -First, get the name of the repository -{% endcomment %} +% First, get the name of the repository {% assign repo_name = site.github.repository_name %} -{% comment %} -`site.github.public_repositories` contains comprehensive information for all public repositories for the organization. We use `where` to extract the part -of the metadata that is relevant to the present repository. -{% endcomment %} +% `site.github.public_repositories` contains comprehensive information for all public repositories for the organization. We use `where` to extract the part +% of the metadata that is relevant to the present repository. {% assign repo_info = site.github.public_repositories | where: "name", repo_name %} -{% comment %} -Now, we can extract the default branch for the repo -{% endcomment %} +% Now, we can extract the default branch for the repo {% assign default_branch = repo_info[0].default_branch %} -{% comment %} -Other variables requested by the template -{% endcomment %} +% Other variables requested by the template {% assign repo_url = site.github.repository_url %} {% assign search_domain_url = site.github.url %} {% assign project_title = site.github.project_title %} diff --git a/_includes/javascript.html b/_includes/javascript.html index fcc74e6e..7b320928 100644 --- a/_includes/javascript.html +++ b/_includes/javascript.html @@ -1,6 +1,4 @@ -{% comment %} - JavaScript used in lesson and workshop pages. -{% endcomment %} +% JavaScript used in lesson and workshop pages. diff --git a/_includes/lesson_footer.html b/_includes/lesson_footer.html index 03091a7c..52b8d97a 100644 --- a/_includes/lesson_footer.html +++ b/_includes/lesson_footer.html @@ -1,8 +1,7 @@ -{% comment %} - Footer for lesson pages. -{% endcomment %} +% Footer for lesson pages. -{% include gh_variables.html %} +```{include} /_includes/gh_variables.html +```
    diff --git a/_includes/life_cycle.html b/_includes/life_cycle.html index efc5b6d9..222eb147 100644 --- a/_includes/life_cycle.html +++ b/_includes/life_cycle.html @@ -27,8 +27,6 @@ {% elsif site.life_cycle == "stable" %} -{% comment %} -We don't do anything special for now -{% endcomment %} +% We don't do anything special for now {% endif %} diff --git a/_includes/links.md b/_includes/links.md index 9b8ecd5a..ffa0238e 100644 --- a/_includes/links.md +++ b/_includes/links.md @@ -1,4 +1,3 @@ -{% include base_path.html %} [cc-by-human]: https://creativecommons.org/licenses/by/4.0/ [cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode [ci]: http://communityin.org/ @@ -6,7 +5,7 @@ [coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html [concept-maps]: https://carpentries.github.io/instructor-training/05-memory/ [contrib-covenant]: https://contributor-covenant.org/ -[contributing]: {{ repo_url }}/blob/{{ source_branch }}/CONTRIBUTING.md +[contributing]: https://github.com/common-workflow-language/user_guide/blob/main/CONTRIBUTING.md [cran-checkpoint]: https://cran.r-project.org/package=checkpoint [cran-knitr]: https://cran.r-project.org/package=knitr [cran-stringr]: https://cran.r-project.org/package=stringr @@ -22,13 +21,13 @@ [json]: http://json.org [kramdown]: https://kramdown.gettalong.org/ [lc-lessons]: https://librarycarpentry.org/lessons/ -[lesson-aio]: {{ relative_root_path }}{% link aio.md %} -[lesson-coc]: {{ relative_root_path }}{% link CODE_OF_CONDUCT.md %} +[lesson-aio]: /aio.md +[lesson-coc]: /CODE_OF_CONDUCT.md [lesson-example]: https://carpentries.github.io/lesson-example/ -[lesson-license]: {{ relative_root_path }}{% link LICENSE.md %} -[lesson-mainpage]: {{ relative_root_path }}{% link index.md %} -[lesson-reference]: {{ relative_root_path }}{% link reference.md %} -[lesson-setup]: {{ relative_root_path }}{% link setup.md %} +[lesson-license]: /LICENSE.md +[lesson-mainpage]: /index.md +[lesson-reference]: /reference.md +[lesson-setup]: /setup.md [mit-license]: https://opensource.org/licenses/mit-license.html [morea]: https://morea-framework.github.io/ [numfocus]: https://numfocus.org/ @@ -46,5 +45,5 @@ [swc-lessons]: https://software-carpentry.org/lessons/ [swc-releases]: https://github.com/swcarpentry/swc-releases [training]: https://carpentries.github.io/instructor-training/ -[workshop-repo]: {{ site.workshop_repo }} +[workshop-repo]: https://github.com/common-workflow-language/user_guide/ [yaml]: http://yaml.org/ diff --git a/_includes/main_title.html b/_includes/main_title.html index 7d17317f..249400d6 100644 --- a/_includes/main_title.html +++ b/_includes/main_title.html @@ -1,8 +1,7 @@ -{% comment %} - Main title for lesson pages. -{% endcomment %} +% Main title for lesson pages. -{% include base_path.html %} +```{include} /_includes/base_path.html +``` {% if site.kind == "lesson" %}

    {{ site.title }}{% if page.title %}: {{ page.title }}{% endif %}

    diff --git a/_includes/manual_episode_order.html b/_includes/manual_episode_order.html index 2928ee85..df990feb 100644 --- a/_includes/manual_episode_order.html +++ b/_includes/manual_episode_order.html @@ -1,54 +1,52 @@ -{% comment %} - This file enables manual episode ordering until - GitHub Pages switches to Jekyll that supports it - without any major hackery. Note, some logic will - be required even when this transition happens - but it won't be as involved as what we have to do - in this file. - - To order lesson episodes or extras manually - (instead of the default alpha-numerical order), - create array variables 'episode_order' and - 'extras_order' in `_config.yml` like so: - - episode_order: - - episodeA - - episodeB - - extras_order: - - extraA - - extraB - - Note that "Reference" page is currently always - added to "Extras" as the first item. - - The main outcomes of the code in this file are: - - 'lesson_episodes' variable that replaces - 'site.episodes' variable when manual episode - order is defined. - - 'lesson_extras' variable that replaces - 'site.extras' variable when manual ordering of - files in '_extras' is used - - 'previous_episode' and 'next_episode' objects - that replace 'page.previous' and 'page.next' variables, - correspondingly, and that have such properties - as 'url' and 'title' and that are used in - 'episode_navbar.html'. - - When episode order is specified manualy, the 'lesson_episodes' - variable contains a list of episode names ("slugs", to be precise; - "slug" is the episode name without '.md'). Therefore, when we - iterate over 'lesson_episodes' (in syllabus.html and navbar.html) , - we have to check whether we use manual episode ordering and, if so, - find the corresponding episode object. This is what we do with the - following code in every loop over 'lesson_episodes': - - {% if site.episode_order %} - {% assign episode = site.episodes | where: "slug", lesson_episode | first %} - {% else %} - {% assign episode = lesson_episode %} - {% endif %} -{% endcomment %} +% This file enables manual episode ordering until +% GitHub Pages switches to Jekyll that supports it +% without any major hackery. Note, some logic will +% be required even when this transition happens +% but it won't be as involved as what we have to do +% in this file. +% +% To order lesson episodes or extras manually +% (instead of the default alpha-numerical order), +% create array variables 'episode_order' and +% 'extras_order' in `_config.yml` like so: +% +% episode_order: +% - episodeA +% - episodeB +% +% extras_order: +% - extraA +% - extraB +% +% Note that "Reference" page is currently always +% added to "Extras" as the first item. +% +% The main outcomes of the code in this file are: +% - 'lesson_episodes' variable that replaces +% 'site.episodes' variable when manual episode +% order is defined. +% - 'lesson_extras' variable that replaces +% 'site.extras' variable when manual ordering of +% files in '_extras' is used +% - 'previous_episode' and 'next_episode' objects +% that replace 'page.previous' and 'page.next' variables, +% correspondingly, and that have such properties +% as 'url' and 'title' and that are used in +% 'episode_navbar.html'. +% +% When episode order is specified manualy, the 'lesson_episodes' +% variable contains a list of episode names ("slugs", to be precise; +% "slug" is the episode name without '.md'). Therefore, when we +% iterate over 'lesson_episodes' (in syllabus.html and navbar.html) , +% we have to check whether we use manual episode ordering and, if so, +% find the corresponding episode object. This is what we do with the +% following code in every loop over 'lesson_episodes': +% +% {% if site.episode_order %} +% {% assign episode = site.episodes | where: "slug", lesson_episode | first %} +% {% else %} +% {% assign episode = lesson_episode %} +% {% endif %} @@ -59,21 +57,17 @@ {% endif %} -{% comment %} - If 'episode_order' is defined, we need to determine - - previous episode object ('previous_episode') - - and next episode object ('next_episode') -{% endcomment %} +% If 'episode_order' is defined, we need to determine +% - previous episode object ('previous_episode') +% - and next episode object ('next_episode') {% if site.episode_order %} {% for lesson_episode in lesson_episodes %} - {% comment %} - We iterate over the specified lesson episodes using - a 'for' loop because we can use - 'forloop.first', 'forloop.last', and 'forloop.index0'. - {% endcomment %} + % We iterate over the specified lesson episodes using + % a 'for' loop because we can use + % 'forloop.first', 'forloop.last', and 'forloop.index0'. {% unless lesson_episode == page.slug %} {% continue %} {% endunless %} @@ -106,6 +100,4 @@ {% assign lesson_extras = site.extras %} {% endif %} -{% comment %} - We do not need to determine "previous" or "next" extra. -{% endcomment %} +% We do not need to determine "previous" or "next" extra. diff --git a/_includes/navbar.html b/_includes/navbar.html index 0362851f..b9d0aa1b 100644 --- a/_includes/navbar.html +++ b/_includes/navbar.html @@ -1,9 +1,9 @@ -{% comment %} - Lesson navigation bar. -{% endcomment %} +% Lesson navigation bar. -{% include gh_variables.html %} -{% include manual_episode_order.html %} +```{include} /_includes/gh_variables.html +``` +```{include} /_includes/manual_episode_order.html +```
a",k.leadingWhitespace=3===b.firstChild.nodeType,k.tbody=!b.getElementsByTagName("tbody").length,k.htmlSerialize=!!b.getElementsByTagName("link").length,k.html5Clone="<:nav>"!==y.createElement("nav").cloneNode(!0).outerHTML,a.type="checkbox",a.checked=!0,c.appendChild(a),k.appendChecked=a.checked,b.innerHTML="",k.noCloneChecked=!!b.cloneNode(!0).lastChild.defaultValue,c.appendChild(b),b.innerHTML="",k.checkClone=b.cloneNode(!0).cloneNode(!0).lastChild.checked,k.noCloneEvent=!0,b.attachEvent&&(b.attachEvent("onclick",function(){k.noCloneEvent=!1}),b.cloneNode(!0).click()),null==k.deleteExpando){k.deleteExpando=!0;try{delete b.test}catch(d){k.deleteExpando=!1}}}(),function(){var b,c,d=y.createElement("div");for(b in{submit:!0,change:!0,focusin:!0})c="on"+b,(k[b+"Bubbles"]=c in a)||(d.setAttribute(c,"t"),k[b+"Bubbles"]=d.attributes[c].expando===!1);d=null}();var X=/^(?:input|select|textarea)$/i,Y=/^key/,Z=/^(?:mouse|pointer|contextmenu)|click/,$=/^(?:focusinfocus|focusoutblur)$/,_=/^([^.]*)(?:\.(.+)|)$/;function aa(){return!0}function ba(){return!1}function ca(){try{return y.activeElement}catch(a){}}m.event={global:{},add:function(a,b,c,d,e){var f,g,h,i,j,k,l,n,o,p,q,r=m._data(a);if(r){c.handler&&(i=c,c=i.handler,e=i.selector),c.guid||(c.guid=m.guid++),(g=r.events)||(g=r.events={}),(k=r.handle)||(k=r.handle=function(a){return typeof m===K||a&&m.event.triggered===a.type?void 0:m.event.dispatch.apply(k.elem,arguments)},k.elem=a),b=(b||"").match(E)||[""],h=b.length;while(h--)f=_.exec(b[h])||[],o=q=f[1],p=(f[2]||"").split(".").sort(),o&&(j=m.event.special[o]||{},o=(e?j.delegateType:j.bindType)||o,j=m.event.special[o]||{},l=m.extend({type:o,origType:q,data:d,handler:c,guid:c.guid,selector:e,needsContext:e&&m.expr.match.needsContext.test(e),namespace:p.join(".")},i),(n=g[o])||(n=g[o]=[],n.delegateCount=0,j.setup&&j.setup.call(a,d,p,k)!==!1||(a.addEventListener?a.addEventListener(o,k,!1):a.attachEvent&&a.attachEvent("on"+o,k))),j.add&&(j.add.call(a,l),l.handler.guid||(l.handler.guid=c.guid)),e?n.splice(n.delegateCount++,0,l):n.push(l),m.event.global[o]=!0);a=null}},remove:function(a,b,c,d,e){var f,g,h,i,j,k,l,n,o,p,q,r=m.hasData(a)&&m._data(a);if(r&&(k=r.events)){b=(b||"").match(E)||[""],j=b.length;while(j--)if(h=_.exec(b[j])||[],o=q=h[1],p=(h[2]||"").split(".").sort(),o){l=m.event.special[o]||{},o=(d?l.delegateType:l.bindType)||o,n=k[o]||[],h=h[2]&&new RegExp("(^|\\.)"+p.join("\\.(?:.*\\.|)")+"(\\.|$)"),i=f=n.length;while(f--)g=n[f],!e&&q!==g.origType||c&&c.guid!==g.guid||h&&!h.test(g.namespace)||d&&d!==g.selector&&("**"!==d||!g.selector)||(n.splice(f,1),g.selector&&n.delegateCount--,l.remove&&l.remove.call(a,g));i&&!n.length&&(l.teardown&&l.teardown.call(a,p,r.handle)!==!1||m.removeEvent(a,o,r.handle),delete k[o])}else for(o in k)m.event.remove(a,o+b[j],c,d,!0);m.isEmptyObject(k)&&(delete r.handle,m._removeData(a,"events"))}},trigger:function(b,c,d,e){var f,g,h,i,k,l,n,o=[d||y],p=j.call(b,"type")?b.type:b,q=j.call(b,"namespace")?b.namespace.split("."):[];if(h=l=d=d||y,3!==d.nodeType&&8!==d.nodeType&&!$.test(p+m.event.triggered)&&(p.indexOf(".")>=0&&(q=p.split("."),p=q.shift(),q.sort()),g=p.indexOf(":")<0&&"on"+p,b=b[m.expando]?b:new m.Event(p,"object"==typeof b&&b),b.isTrigger=e?2:3,b.namespace=q.join("."),b.namespace_re=b.namespace?new RegExp("(^|\\.)"+q.join("\\.(?:.*\\.|)")+"(\\.|$)"):null,b.result=void 0,b.target||(b.target=d),c=null==c?[b]:m.makeArray(c,[b]),k=m.event.special[p]||{},e||!k.trigger||k.trigger.apply(d,c)!==!1)){if(!e&&!k.noBubble&&!m.isWindow(d)){for(i=k.delegateType||p,$.test(i+p)||(h=h.parentNode);h;h=h.parentNode)o.push(h),l=h;l===(d.ownerDocument||y)&&o.push(l.defaultView||l.parentWindow||a)}n=0;while((h=o[n++])&&!b.isPropagationStopped())b.type=n>1?i:k.bindType||p,f=(m._data(h,"events")||{})[b.type]&&m._data(h,"handle"),f&&f.apply(h,c),f=g&&h[g],f&&f.apply&&m.acceptData(h)&&(b.result=f.apply(h,c),b.result===!1&&b.preventDefault());if(b.type=p,!e&&!b.isDefaultPrevented()&&(!k._default||k._default.apply(o.pop(),c)===!1)&&m.acceptData(d)&&g&&d[p]&&!m.isWindow(d)){l=d[g],l&&(d[g]=null),m.event.triggered=p;try{d[p]()}catch(r){}m.event.triggered=void 0,l&&(d[g]=l)}return b.result}},dispatch:function(a){a=m.event.fix(a);var b,c,e,f,g,h=[],i=d.call(arguments),j=(m._data(this,"events")||{})[a.type]||[],k=m.event.special[a.type]||{};if(i[0]=a,a.delegateTarget=this,!k.preDispatch||k.preDispatch.call(this,a)!==!1){h=m.event.handlers.call(this,a,j),b=0;while((f=h[b++])&&!a.isPropagationStopped()){a.currentTarget=f.elem,g=0;while((e=f.handlers[g++])&&!a.isImmediatePropagationStopped())(!a.namespace_re||a.namespace_re.test(e.namespace))&&(a.handleObj=e,a.data=e.data,c=((m.event.special[e.origType]||{}).handle||e.handler).apply(f.elem,i),void 0!==c&&(a.result=c)===!1&&(a.preventDefault(),a.stopPropagation()))}return k.postDispatch&&k.postDispatch.call(this,a),a.result}},handlers:function(a,b){var c,d,e,f,g=[],h=b.delegateCount,i=a.target;if(h&&i.nodeType&&(!a.button||"click"!==a.type))for(;i!=this;i=i.parentNode||this)if(1===i.nodeType&&(i.disabled!==!0||"click"!==a.type)){for(e=[],f=0;h>f;f++)d=b[f],c=d.selector+" ",void 0===e[c]&&(e[c]=d.needsContext?m(c,this).index(i)>=0:m.find(c,this,null,[i]).length),e[c]&&e.push(d);e.length&&g.push({elem:i,handlers:e})}return h]","i"),ha=/^\s+/,ia=/<(?!area|br|col|embed|hr|img|input|link|meta|param)(([\w:]+)[^>]*)\/>/gi,ja=/<([\w:]+)/,ka=/\s*$/g,ra={option:[1,""],legend:[1,"
","
"],area:[1,"",""],param:[1,"",""],thead:[1,"","
"],tr:[2,"","
"],col:[2,"","
"],td:[3,"","
"],_default:k.htmlSerialize?[0,"",""]:[1,"X
","
"]},sa=da(y),ta=sa.appendChild(y.createElement("div"));ra.optgroup=ra.option,ra.tbody=ra.tfoot=ra.colgroup=ra.caption=ra.thead,ra.th=ra.td;function ua(a,b){var c,d,e=0,f=typeof a.getElementsByTagName!==K?a.getElementsByTagName(b||"*"):typeof a.querySelectorAll!==K?a.querySelectorAll(b||"*"):void 0;if(!f)for(f=[],c=a.childNodes||a;null!=(d=c[e]);e++)!b||m.nodeName(d,b)?f.push(d):m.merge(f,ua(d,b));return void 0===b||b&&m.nodeName(a,b)?m.merge([a],f):f}function va(a){W.test(a.type)&&(a.defaultChecked=a.checked)}function wa(a,b){return m.nodeName(a,"table")&&m.nodeName(11!==b.nodeType?b:b.firstChild,"tr")?a.getElementsByTagName("tbody")[0]||a.appendChild(a.ownerDocument.createElement("tbody")):a}function xa(a){return a.type=(null!==m.find.attr(a,"type"))+"/"+a.type,a}function ya(a){var b=pa.exec(a.type);return b?a.type=b[1]:a.removeAttribute("type"),a}function za(a,b){for(var c,d=0;null!=(c=a[d]);d++)m._data(c,"globalEval",!b||m._data(b[d],"globalEval"))}function Aa(a,b){if(1===b.nodeType&&m.hasData(a)){var c,d,e,f=m._data(a),g=m._data(b,f),h=f.events;if(h){delete g.handle,g.events={};for(c in h)for(d=0,e=h[c].length;e>d;d++)m.event.add(b,c,h[c][d])}g.data&&(g.data=m.extend({},g.data))}}function Ba(a,b){var c,d,e;if(1===b.nodeType){if(c=b.nodeName.toLowerCase(),!k.noCloneEvent&&b[m.expando]){e=m._data(b);for(d in e.events)m.removeEvent(b,d,e.handle);b.removeAttribute(m.expando)}"script"===c&&b.text!==a.text?(xa(b).text=a.text,ya(b)):"object"===c?(b.parentNode&&(b.outerHTML=a.outerHTML),k.html5Clone&&a.innerHTML&&!m.trim(b.innerHTML)&&(b.innerHTML=a.innerHTML)):"input"===c&&W.test(a.type)?(b.defaultChecked=b.checked=a.checked,b.value!==a.value&&(b.value=a.value)):"option"===c?b.defaultSelected=b.selected=a.defaultSelected:("input"===c||"textarea"===c)&&(b.defaultValue=a.defaultValue)}}m.extend({clone:function(a,b,c){var d,e,f,g,h,i=m.contains(a.ownerDocument,a);if(k.html5Clone||m.isXMLDoc(a)||!ga.test("<"+a.nodeName+">")?f=a.cloneNode(!0):(ta.innerHTML=a.outerHTML,ta.removeChild(f=ta.firstChild)),!(k.noCloneEvent&&k.noCloneChecked||1!==a.nodeType&&11!==a.nodeType||m.isXMLDoc(a)))for(d=ua(f),h=ua(a),g=0;null!=(e=h[g]);++g)d[g]&&Ba(e,d[g]);if(b)if(c)for(h=h||ua(a),d=d||ua(f),g=0;null!=(e=h[g]);g++)Aa(e,d[g]);else Aa(a,f);return d=ua(f,"script"),d.length>0&&za(d,!i&&ua(a,"script")),d=h=e=null,f},buildFragment:function(a,b,c,d){for(var e,f,g,h,i,j,l,n=a.length,o=da(b),p=[],q=0;n>q;q++)if(f=a[q],f||0===f)if("object"===m.type(f))m.merge(p,f.nodeType?[f]:f);else if(la.test(f)){h=h||o.appendChild(b.createElement("div")),i=(ja.exec(f)||["",""])[1].toLowerCase(),l=ra[i]||ra._default,h.innerHTML=l[1]+f.replace(ia,"<$1>")+l[2],e=l[0];while(e--)h=h.lastChild;if(!k.leadingWhitespace&&ha.test(f)&&p.push(b.createTextNode(ha.exec(f)[0])),!k.tbody){f="table"!==i||ka.test(f)?""!==l[1]||ka.test(f)?0:h:h.firstChild,e=f&&f.childNodes.length;while(e--)m.nodeName(j=f.childNodes[e],"tbody")&&!j.childNodes.length&&f.removeChild(j)}m.merge(p,h.childNodes),h.textContent="";while(h.firstChild)h.removeChild(h.firstChild);h=o.lastChild}else p.push(b.createTextNode(f));h&&o.removeChild(h),k.appendChecked||m.grep(ua(p,"input"),va),q=0;while(f=p[q++])if((!d||-1===m.inArray(f,d))&&(g=m.contains(f.ownerDocument,f),h=ua(o.appendChild(f),"script"),g&&za(h),c)){e=0;while(f=h[e++])oa.test(f.type||"")&&c.push(f)}return h=null,o},cleanData:function(a,b){for(var d,e,f,g,h=0,i=m.expando,j=m.cache,l=k.deleteExpando,n=m.event.special;null!=(d=a[h]);h++)if((b||m.acceptData(d))&&(f=d[i],g=f&&j[f])){if(g.events)for(e in g.events)n[e]?m.event.remove(d,e):m.removeEvent(d,e,g.handle);j[f]&&(delete j[f],l?delete d[i]:typeof d.removeAttribute!==K?d.removeAttribute(i):d[i]=null,c.push(f))}}}),m.fn.extend({text:function(a){return V(this,function(a){return void 0===a?m.text(this):this.empty().append((this[0]&&this[0].ownerDocument||y).createTextNode(a))},null,a,arguments.length)},append:function(){return this.domManip(arguments,function(a){if(1===this.nodeType||11===this.nodeType||9===this.nodeType){var b=wa(this,a);b.appendChild(a)}})},prepend:function(){return this.domManip(arguments,function(a){if(1===this.nodeType||11===this.nodeType||9===this.nodeType){var b=wa(this,a);b.insertBefore(a,b.firstChild)}})},before:function(){return this.domManip(arguments,function(a){this.parentNode&&this.parentNode.insertBefore(a,this)})},after:function(){return this.domManip(arguments,function(a){this.parentNode&&this.parentNode.insertBefore(a,this.nextSibling)})},remove:function(a,b){for(var c,d=a?m.filter(a,this):this,e=0;null!=(c=d[e]);e++)b||1!==c.nodeType||m.cleanData(ua(c)),c.parentNode&&(b&&m.contains(c.ownerDocument,c)&&za(ua(c,"script")),c.parentNode.removeChild(c));return this},empty:function(){for(var a,b=0;null!=(a=this[b]);b++){1===a.nodeType&&m.cleanData(ua(a,!1));while(a.firstChild)a.removeChild(a.firstChild);a.options&&m.nodeName(a,"select")&&(a.options.length=0)}return this},clone:function(a,b){return a=null==a?!1:a,b=null==b?a:b,this.map(function(){return m.clone(this,a,b)})},html:function(a){return V(this,function(a){var b=this[0]||{},c=0,d=this.length;if(void 0===a)return 1===b.nodeType?b.innerHTML.replace(fa,""):void 0;if(!("string"!=typeof a||ma.test(a)||!k.htmlSerialize&&ga.test(a)||!k.leadingWhitespace&&ha.test(a)||ra[(ja.exec(a)||["",""])[1].toLowerCase()])){a=a.replace(ia,"<$1>");try{for(;d>c;c++)b=this[c]||{},1===b.nodeType&&(m.cleanData(ua(b,!1)),b.innerHTML=a);b=0}catch(e){}}b&&this.empty().append(a)},null,a,arguments.length)},replaceWith:function(){var a=arguments[0];return this.domManip(arguments,function(b){a=this.parentNode,m.cleanData(ua(this)),a&&a.replaceChild(b,this)}),a&&(a.length||a.nodeType)?this:this.remove()},detach:function(a){return this.remove(a,!0)},domManip:function(a,b){a=e.apply([],a);var c,d,f,g,h,i,j=0,l=this.length,n=this,o=l-1,p=a[0],q=m.isFunction(p);if(q||l>1&&"string"==typeof p&&!k.checkClone&&na.test(p))return this.each(function(c){var d=n.eq(c);q&&(a[0]=p.call(this,c,d.html())),d.domManip(a,b)});if(l&&(i=m.buildFragment(a,this[0].ownerDocument,!1,this),c=i.firstChild,1===i.childNodes.length&&(i=c),c)){for(g=m.map(ua(i,"script"),xa),f=g.length;l>j;j++)d=i,j!==o&&(d=m.clone(d,!0,!0),f&&m.merge(g,ua(d,"script"))),b.call(this[j],d,j);if(f)for(h=g[g.length-1].ownerDocument,m.map(g,ya),j=0;f>j;j++)d=g[j],oa.test(d.type||"")&&!m._data(d,"globalEval")&&m.contains(h,d)&&(d.src?m._evalUrl&&m._evalUrl(d.src):m.globalEval((d.text||d.textContent||d.innerHTML||"").replace(qa,"")));i=c=null}return this}}),m.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){m.fn[a]=function(a){for(var c,d=0,e=[],g=m(a),h=g.length-1;h>=d;d++)c=d===h?this:this.clone(!0),m(g[d])[b](c),f.apply(e,c.get());return this.pushStack(e)}});var Ca,Da={};function Ea(b,c){var d,e=m(c.createElement(b)).appendTo(c.body),f=a.getDefaultComputedStyle&&(d=a.getDefaultComputedStyle(e[0]))?d.display:m.css(e[0],"display");return e.detach(),f}function Fa(a){var b=y,c=Da[a];return c||(c=Ea(a,b),"none"!==c&&c||(Ca=(Ca||m("