Merge pull request #281 from common-workflow-language/main

2022 Week 41 release

.github/workflows/gh-pages.yaml

@@ -17,7 +17,7 @@ jobs:
 
       - name: Install apt packages
         run: |
-          sudo apt-get install -y graphviz
+          sudo apt-get install -y graphviz tree
 
       - name: Set up Python
         uses: actions/setup-python@v4

.gitignore

@@ -10,6 +10,7 @@ _site
 .Rhistory
 .RData
 _build/
+build/
 *.egg-info/
 
 src/_includes/cwl/**/output.txt

.readthedocs.yaml

@@ -9,6 +9,7 @@ build:
     nodejs: "16"
   apt_packages:
     - graphviz
+    - tree
 
 sphinx:
   configuration: src/conf.py

.zenodo.json

@@ -6,18 +6,135 @@
     "publication_type": "softwaredocumentation",
     "creators": [
         {
-            "affiliation": "European Molecular Biology Laboratory",
-            "orcid": "https://orcid.org/0000-0003-1766-456X",
-            "name": "Toby Hodges"
+            "name": "Alain Domissy"
+	},
+	{
+            "name": "Andrew Jesaitis"
+	},
+	{
+            "name": "bamiwoaluko"
+	},
+	{
+            "orcid": "https://orcid.org/0000-0002-6206-4638>",
+            "name": "Benjamin Carr"
+	},
+        {
+            "name": "Michele Mastropietro",
+	    "orcid": "https://orcid.org/0000-0002-6324-5713"
+	},
+	{
+            "name": "Emannuel Fernandes de Oliveira Carvalho"
+	},
+	{
+            "name": "Eugene Miloslavsky"
+	},
+	{
+            "name": "Robin Long",
+	    "orcid": "https://orcid.org/0000-0003-2249-645X"
+	},
+	{
+            "name": "Ngumih Fien"
+	},
+	{
+            "name": "gathoni-k"
+	},
+	{
+            "name": "Henry Liu"
+	},
+	{
+            "name": "Marijke J. van Baren"
         },
         {
-            "affiliation": "Common Workflow Language project",
+            "name": "jessMaia"
+	},
+	{
+            "name": "Bruno P. Kinoshita",
+	    "orcid": "https://orcid.org/0000-0001-8250-4074"
+	},
+	{
+            "name": "Kaushik Ghose",
+	    "orcid": "https://orcid.org/0000-0003-2933-1260"
+	},
+	{
+            "name": "Konstantin Taletskiy",
+	    "orcid": "https://orcid.org/0000-0001-6846-9815"
+	},
+	{
+            "name": "Kushal Beniwal"
+	},
+	{
+            "name": "Mark A. Jensen",
+	    "orcid": "https://orcid.org/0000-0001-5215-101X"
+	},
+	{
+            "name": "Levai Mackenzie Ágbàrà"
+	},
+	{
+            "name": "Manabu Ishii",
+            "orcid": "https://orcid.org/0000-0002-5843-4712"
+	},
+	{
+	    "name": "medcelerate"
+	},
+        {
+            "name": "Michael R. Crusoe",
             "orcid": "https://orcid.org/0000-0002-2961-9670",
-            "name": "Michael R. Crusoe"
+            "affiliation": "Common Workflow Language project"
+        },
+	{
+            "name": "Ruth B. McCole",
+	    "orcid": "https://orcid.org/0000-0002-1861-7055"
+	},
+	{
+            "name": "sersorrel"
+	},
+	{
+            "name": "Adrian Sharma"
+	},
+	{
+            "name": "Steffen Möller",
+	    "orcid": "https://orcid.org/0000-0002-7187-4683"
+	},
+	{
+            "name": "Oghenemaro Akpobi"
+	},
+	{
+            "name": "Stian Soiland-Reyes",
+	    "orcid": "https://orcid.org/0000-0001-9842-9718"
+	},
+	{
+            "name": "Luka Stojanovic"
+	},
+	{
+            "name": "Sarah Wait Zaranek",
+	    "orcid": "https://orcid.org/0000-0003-4716-9121"
+	},
+	{
+            "name": "Peter Amstutz",
+	    "orcid": "https://orcid.org/0000-0003-3566-7705"
+	},
+        {
+            "name": "Toby Hodges",
+            "affiliation": "European Molecular Biology Laboratory",
+            "orcid": "https://orcid.org/0000-0003-1766-456X"
+        },
+	{
+            "name": "Tomoya Tanjo",
+	    "orcid": "https://orcid.org/0000-0002-4421-9659"
+	},
+	{
+            "name": "Daiki Tsuchiya",
+	    "orcid": "https://orcid.org/0000-0003-2112-9316"
+	},
+	{
+            "name": "Wolfgang Gerlach",
+	    "orcid": "https://orcid.org/0000-0002-1480-1242"
+	},
+	{
+            "name": "Zipho Mashologu"
         }
     ],
     "access_right": "open",
-    "notes": "Based off of the excellent Software/Data Carpentry templates: https://doi.org/10.5281/zenodo.838778",
     "related_identifiers": [
         {
             "scheme": "url",

AUTHORS.md

@@ -1 +1,43 @@
-FIXME: list authors' names and email addresses.
+Thank you to the following contributors (in alphabetical order by user name):
+* Alain Domissy (@alaindomissy)
+* Andrew Jesaitis (@andrewjesaitis)
+* @bamiwoaluko
+* Benjamin Carr (@BenjaminHCCarr) <https://orcid.org/0000-0002-6206-4638>
+* Michele Mastropietro (@elehcim) <https://orcid.org/0000-0002-6324-5713>
+* Emannuel Fernandes de Oliveira Carvalho (@emannuelOC)
+* Eugene Miloslavsky (@emiloslavsky)
+* Robin Long (@longr) <https://orcid.org/0000-0003-2249-645X>
+* Ngumih Fien (@Fienne)
+* @gathoni-k
+* Henry Liu (@HenryLiu0)
+* Marijke J. van Baren (@Jeltje)
+* @jessMaia
+* Bruno P. Kinoshita (@kinow) <https://orcid.org/0000-0001-8250-4074>
+* Kaushik Ghose (@kghose) <https://orcid.org/0000-0003-2933-1260>
+* Konstantin Taletskiy (@ktaletsk) <https://orcid.org/0000-0001-6846-9815>
+* Kushal Beniwal (@KushalBeniwal)
+* Mark A. Jensen  (@majensen) <https://orcid.org/0000-0001-5215-101X>
+* Levai Mackenzie Ágbàrà (@Mackenzie-OO7)
+* Manabu Ishii (@manabuishii) <https://orcid.org/0000-0002-5843-4712>
+* @medcelerate
+* Michael Crusoe (@mr-c) <http://orcid.org/0000-0002-2961-9670>
+* Ruth B. McCole  (@rmccole) <https://orcid.org/0000-0002-1861-7055>
+* @sersorrel
+* Adrian Sharma (@sharmatime)
+* Steffen Möller (@smoe) https://orcid.org/0000-0002-7187-4683
+* Oghenemaro Akpobi (@Smyja)
+* Stian Soiland-Reyes (@stain) <https://orcid.org/0000-0001-9842-9718>
+* Luka Stojanovic (@StarvingMarvin)
+* Sarah Wait Zaranek (@swzCuroverse) https://orcid.org/0000-0003-4716-9121
+* Peter Amstutz (@tetron) <https://orcid.org/0000-0003-3566-7705>
+* Toby Hodges (@tobyhodges) <https://orcid.org/0000-0003-1766-456X>
+* Tomoya Tanjo (@tom-tan) <https://orcid.org/0000-0002-4421-9659>
+* Daiki Tsuchiya (@tsuchi8) <https://orcid.org/0000-0003-2112-9316>
+* Wolfgang Gerlach (@wgerlach) <https://orcid.org/0000-0002-1480-1242>
+* Zipho Mashologu (@zipho)
+
+Thanks to:
+* [Common Workflow Language community](https://www.commonwl.org/community/)
+  and the members of the CWL forums and chat rooms.
+* [ELIXIR](https://elixir-europe.org/), and ELIXIR Netherlands
+* CZI Essential Open Source Software for Science (EOSS)

CITATION.md

@@ -1,9 +1,13 @@
 # Citation
 
-To cite the Common Workflow Language  and the CWL project in a scholary work, please use:
+To cite the Common Workflow Language project in a scholary work, please use:
 
-Michael R. Crusoe, Sanne Abeln, Alexandru Iosup, Peter Amstutz, John Chilton, Nebojša Tijanić, Hervé Ménager, Stian Soiland-Reyes, Bogdan Gavrilović, Carole Goble, and The CWL Community. 2022. Methods included: standardizing computational reuse and portability with the Common Workflow Language. Commun. ACM 65, 6 (June 2022), 54–63. https://doi.org/10.1145/3486897
+Michael R. Crusoe, Sanne Abeln, Alexandru Iosup, Peter Amstutz, John Chilton, Nebojša Tijanić,
+Hervé Ménager, Stian Soiland-Reyes, Bogdan Gavrilović, Carole Goble, and The CWL Community. 2022.
+Methods Included: Standardizing Computational Reuse and Portability with the Common Workflow Language.
+Commun. ACM 65, 6 (June 2022), 54–63. https://doi.org/10.1145/3486897
 
+```
 @article{10.1145/3486897,
 author = {Crusoe, Michael R. and Abeln, Sanne and Iosup, Alexandru and Amstutz, Peter and Chilton, John and Tijani\'{c}, Neboj\v{s}a and M\'{e}nager, Herv\'{e} and Soiland-Reyes, Stian and Gavrilovi\'{c}, Bogdan and Goble, Carole and Community, The CWL},
 title = {Methods Included: Standardizing Computational Reuse and Portability with the Common Workflow Language},
@@ -22,6 +26,7 @@ month = {may},
 pages = {54–63},
 numpages = {10}
 }
+```
 
 To cite just the CWL standards themselves, please use the following inclusive of the DOI:
 
@@ -32,6 +37,7 @@ Stojanovic, Luka (2016): Common Workflow Language, v1.0. Specification,
 Common Workflow Language working group. https://w3id.org/cwl/v1.0/
 https://dx.doi.org/10.6084/m9.figshare.3115156.v2
 
+```
 @data{cwl,
   doi = {10.6084/m9.figshare.3115156.v2},
   url = {https://doi.org/10.6084/m9.figshare.3115156.v2},
@@ -45,8 +51,9 @@ Luka Stojanovic
   title = {Common Workflow Language, v1.0},
   year = {2016}
 }
+```
 
-# the above is from https://github.com/common-workflow-language/common-workflow-language/blob/main/CITATION
+[//]: # (the above is from https://github.com/common-workflow-language/common-workflow-language/blob/main/CITATION.cff)
 
 Our preferred DOI for the "CWL User Guide" is http://doi.org/10.5281/zenodo.840129
 

CONTRIBUTING.md

@@ -41,9 +41,14 @@ 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].
+
+4. To build and run the user guide locally, see **Building** below
+
+**Note:** The published version of the user guide <https://www.commonwl.org/user_guide/> is built from the `release` branch.
+New changes are gathered on the default (`main`) branch which is built at <https://common-workflow-languageuser-guide.readthedocs.io/en/latest/>
+as a preview. Once we collect many changes from the `main` branch, we merge them into the `release` branch.
 
-4. To build and run the user guide locally, see [building][#building].
 
 Pull requests include an automatic preview provided by
 [ReadTheDocs](https://readthedocs.org/projects/common-workflow-languageuser-guide/).
@@ -101,11 +106,13 @@ in `Makefile`).
 # Create and activate a virtual environment
 python -m venv venv
 source venv/bin/activate
+# update the version of pip, setuptools, and wheel
+(venv) pip install -U pip setuptools wheel
 # Install the dependencies in your virtual environment
-(venv) pip install -e .[all]
+(venv) pip install .[all]
 # Create the HTML to visualize locally
 (venv) make html
-(venv) firefox _build/index.html
+(venv) open _build/index.html
 # Or you can start a serve that watches for local file changes
 (venv) make watch
 # Open <http://localhost:8000/> in your browser
@@ -118,6 +125,56 @@ source venv/bin/activate
 > correctly, but failure to deploy the production version after the pull request
 > gets merged.
 
+## Style Guide
+
+We must use the phrase "CWL standards" or "CWL open standards" when talking about CWL.
+We must use the word "specification" only when talking specifically about the CWL
+specification document.
+
+Whenever a page is updated we must verify that it does not break existing
+links, both internal and external. The `make html` command will fail if Sphinx detects broken links.
+It only works for links managed by Sphinx (i.e. table of contents links,
+or links to Markdown pages). For simple HTML links (e.g. `< href=>` or
+markdown external links) pull request reviewers must verify that links
+are still working after the change.
+
+Use “tool description” not “tool wrapper” for describing the first argument
+given to the `cwl-runner` or `cwltool` commands.
+
+### Code examples
+
+To include code into a Markdown file you have two options. For external files use
+the following command:
+
+````
+```{literalinclude} /_includes/cwl/hello_world.cwl
+:language: cwl
+```
+````
+
+For code examples in the same page, you can use fence blocks.
+
+````
+```bash
+echo "Hello world"
+```
+````
+
+If you would like to customize the syntax highlighting styles
+you will have to customize the Sphinx and Pygments settings.
+To preview Pygments output with different styles, use their
+[Pygments demo tool](https://pygments.org/demo/).
+
+### Creating Links
+
+Sphinx and the theme are configured to auto-generate anchor slug
+links for sections. So sections like ``## cwl standard`` are translated
+into an anchor link `#cwl-standard`.
+
+If you are having trouble with links to sections or code blocks, it might
+be due to duplicated sections, or to spaces or other characters. To
+preview the generated links, use the `myst-anchors` tool.
+
 ## Other Resources
 
 General discussion of [Common Workflow Language][cwl-site] project
@@ -128,7 +185,9 @@ which everyone is welcome to join.
 [github]: https://github.com
 [github-flow]: https://guides.github.com/introduction/flow/
 [github-join]: https://github.com/join
-[how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github
+[how-contribute]: https://docs.github.com/en/get-started/quickstart/contributing-to-projects
 [issues]: https://github.com/common-workflow-language/user_guide/issues
+[cwl-issues]: https://github.com/common-workflow-language/common-workflow-language/issues
 [repo]: https://github.com/common-workflow-language/user_guide
 [cwl-site]: https://www.commonwl.org/
+[using-github]: https://docs.github.com/en/get-started/