Merge pull request #4 from tobyhodges/config_and_setup

Initial config and setup

Author: mr-c

_config.yml

@@ -6,12 +6,12 @@
 carpentry: "cwl"
 
 # Overall title for pages.
-title: "Lesson Title"
+title: "Common Workflow Language User Guide"
 
 # Contact.  This *must* include the protocol: if it's an email
 # address, it must look like "mailto:[email protected]",
 # or if it's a URL, "https://gitter.im/username/ProjectName".
-contact: "mailto:lessons@software-carpentry.org"
+contact: "http://www.commonwl.org/#Support"
 
 #------------------------------------------------------------
 # Generic settings (should not need to change).
@@ -22,26 +22,26 @@ kind: "lesson"
 
 # Magic to make URLs resolve both locally and on GitHub.
 # See https://help.github.com/articles/repository-metadata-on-github-pages/.
-repository: <USERNAME>/<PROJECT>
+repository: common-workflow-language/user-guide
 
 # Sites.
-amy_site: "https://amy.software-carpentry.org/workshops"
-dc_site: "http://datacarpentry.org"
-swc_github: "https://github.com/swcarpentry"
-swc_site: "https://software-carpentry.org"
-swc_pages: "https://swcarpentry.github.io"
-lc_site: "http://librarycarpentry.github.io/"
-template_repo: "https://github.com/swcarpentry/styles"
-example_repo: "https://github.com/swcarpentry/lesson-example"
-example_site: "https://swcarpentry.github.com/lesson-example"
-workshop_repo: "https://github.com/swcarpentry/workshop-template"
-workshop_site: "https://swcarpentry.github.io/workshop-template"
-training_site: "https://swcarpentry.github.io/instructor-training"
+# amy_site: "https://amy.software-carpentry.org/workshops"
+# dc_site: "http://datacarpentry.org"
+# swc_github: "https://github.com/swcarpentry"
+# swc_site: "https://software-carpentry.org"
+# swc_pages: "https://swcarpentry.github.io"
+# lc_site: "http://librarycarpentry.github.io/"
+# template_repo: "https://github.com/swcarpentry/styles"
+# example_repo: "https://github.com/swcarpentry/lesson-example"
+# example_site: "https://swcarpentry.github.com/lesson-example"
+# workshop_repo: "https://github.com/swcarpentry/workshop-template"
+# workshop_site: "https://swcarpentry.github.io/workshop-template"
+# training_site: "https://swcarpentry.github.io/instructor-training"
 
 # Surveys.
-pre_survey: "https://www.surveymonkey.com/r/swc_pre_workshop_v1?workshop_id="
-post_survey: "https://www.surveymonkey.com/r/swc_post_workshop_v1?workshop_id="
-training_post_survey: "https://www.surveymonkey.com/r/post-instructor-training"
+# pre_survey: "https://www.surveymonkey.com/r/swc_pre_workshop_v1?workshop_id="
+# post_survey: "https://www.surveymonkey.com/r/swc_post_workshop_v1?workshop_id="
+# training_post_survey: "https://www.surveymonkey.com/r/post-instructor-training"
 
 # Start time in minutes (0 to be clock-independent, 540 to show a start at 09:00 am).
 start_time: 0

_episodes/01-introduction.md

@@ -3,13 +3,30 @@ title: "Introduction"
 teaching: 0
 exercises: 0
 questions:
-- "Key question"
+- "What is Common Workflow Language?"
+- "Why might I want to learn to use CWL?"
 objectives:
-- "First objective."
+- "Learn what CWL is."
+- "Learn about the motivation behind the project."
 keypoints:
-- "First key point."
+- "CWL describes command line tools and workflows."
+- "CWL is not software."
+- "Descriptions in CWL aid portability between environments"
 ---
-Content here
 
-{% include links.md %}
+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
+of platforms that support the CWL standard.
+
+CWL has roots in "make" and many similar tools that determine order of
+execution based on dependencies between tasks.  However unlike "make", CWL
+tasks are isolated and you must be explicit about your inputs and outputs.  The
+benefit of explicitness and isolation are flexibility, portability, and
+scalability: tools and workflows described with CWL can transparently leverage
+technologies such as Docker, be used with CWL implementations from different
+vendors, and 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 %}

_episodes/recommended-practices.md

@@ -0,0 +1,20 @@
+# Recommended CWL Practices
+
+Below are a set of recommended good practices to keep in mind when writing a Common Workflow Language description for a tool or workflow. These guidelines are presented for consideration on a scale of usefulness: more is better, not all are required.
+
+- [ ] No `type: string` descriptions for names of input or reference files/directories.
+- [ ] Include a license that allows for re-use by anyone, e.g. [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0#apply). [Example of license inclusion](https://github.com/ProteinsWebTeam/ebi-metagenomics-cwl/blob/master/workflows/emg-assembly.cwl#L200).
+- [ ] Include [attribution information](https://github.com/ProteinsWebTeam/ebi-metagenomics-cwl/blob/master/workflows/emg-assembly.cwl#L200) for the CWL description author(s).
+- [ ] In tool descriptions, list dependencies using short name(s) under `SoftwareRequirement`.
+- [ ] Include [SciCrunch](https://github.com/common-workflow-language/common-workflow-language/issues/scicrunch.org) identifiers for dependencies in `https://identifiers.org/rrid/RRID:SCR_NNNNNN` format.
+- [ ] All `input` and `output` identifiers should reflect their conceptual identity. No `foo_input`, `foo_file`, `result`, `input`, `output`, or other uninformative names.
+- [ ] In tool descriptions, include a list of version(s) of the tool that are known to work.
+- [ ] `format` should be specified for all input and output `File`s. Bioinformatics tools should use format identifiers from [EDAM](http://edamontology.org/format_1915). See also `iana:text/plain`, `iana:text/tab-separated-values` with `$namespaces: { iana: "https://www.iana.org/assignments/media-types/" }`. [Full IANA media type list](http://www.iana.org/assignments/media-types/media-types.xhtml) (also known as MIME types).
+- [ ] Mark all input and output `File`s that are read or written to in a streaming compatible way (once, no random-access), as `streamable: true`.
+- [ ] Each `CommandLineTool` description should focus on a single operation only, even if the (sub)command is capable of more.
+- [ ] Custom types should be defined with one external YAML per type definition for re-use.
+- [ ] Include a top level short `label` summarising the tool/workflow.
+- [ ] If useful, include a top level `doc` as well. This should provide a longer, more detailed description than was provided in the top level `label` (see above).
+- [ ] Use `type: enum` instead of `type: string` for elements with a fixed list of valid values.
+- [ ] Evaluate all use of JavaScript for possible elimination or replacement. One common example: manipulating `File` names and paths? Consider whether one of the [built in `File` properties](http://www.commonwl.org/v1.0/CommandLineTool.html#File) like `basename`, `nameroot`, `nameext`, etc, could be used instead.
+- [ ] Give the tool description to a colleague at a different institution to test and provide feedback.

_includes/lesson_footer.html

@@ -6,12 +6,14 @@
     <div class="col-md-6" align="left">
       <h4>
 	Copyright &copy; 2016–{{ 'now' | date: "%Y" }}
-	{% if site.carpentry == "swc" %}
+    {% if site.carpentry == "swc" %}
 	<a href="{{ site.swc_site }}">Software Carpentry Foundation</a>
 	{% elsif site.carpentry == "dc" %}
 	<a href="{{ site.dc_site }}">Data Carpentry</a>
 	{% elsif site.carpentry == "lc" %}
 	<a href="{{ site.lc_site }}">Library Carpentry</a>
+    {% elsif site.carpentry == "cwl" %}
+	<a href="{{ site.swc_site }}">Common Workflow Language Project</a>
 	{% endif %}
       </h4>
     </div>

_includes/navbar.html

@@ -24,6 +24,10 @@
       <a href="{{ site.lc_site }}" class="pull-left">
         <img class="navbar-logo" src="{{ page.root }}/assets/img/lc-icon-black.png" alt="Library Carpentry logo" />
       </a>
+      {% elsif site.carpentry == "cwl" %}
+      <a href="{{ site.swc_site }}" class="pull-left">
+        <img class="navbar-logo" src="{{ page.root }}/assets/img/cwl-apple-icon-180x180.png" alt="Common Workflow Language logo" />
+      </a>
       {% endif %}
 
       {% comment %} Always show link to home page. {% endcomment %}

assets/img/cwl-apple-icon-180x180.png

@@ -2,9 +2,18 @@
 layout: lesson
 root: .
 ---
-FIXME: home page introduction
+Hello!
+
+This guide will introduce you to writing tool wrappers and workflows using the Common Workflow Language (CWL). This guide describes the current stable specification, version 1.0.
+
+Note: This document is a work in progress. Not all features are covered, yet.
 
 > ## Prerequisites
 >
-> FIXME
+> A text editor
+>
+> A CWL runner e.g. the [reference implementation](cwltool-repo) (see [the project homepage](cwl-home) for a full list)
 {: .prereq}
+
+[cwl-home]: http://www.commonwl.org
+[cwltool-repo]: https://github.com/common-workflow-language/cwltool