Creating a preview of the outline proposed

Author: kinow

.github/workflows/gh-pages.yaml

@@ -34,7 +34,7 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-pip-
       - name: Install dependencies
-        run: python3 -m pip install -U -r ./requirements.txt
+        run: python3 -m pip install -U -e .[all]
 
       - name: Build documentation
         run: make html

.gitignore

@@ -11,3 +11,4 @@ _site
 .RData
 
 _build/
+*.egg-info/

.readthedocs.yaml

@@ -0,0 +1,18 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+sphinx:
+  configuration: src/conf.py
+  builder: html
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - all
+

.travis.yml

@@ -13,9 +13,9 @@ branches:
     - main
     - /.*/
 
-before_script:
+install:
   - pip install -U pip setuptools wheel typing
-  - pip install cwltool cwltest html5lib
+  - pip install -e .[all]
 
 script:
   - make RUNNER=cwltool unittest-examples

AUTHORS renamed to AUTHORS.md

@@ -3,38 +3,45 @@
 
 # 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
+SPHINXOPTS		= "-W"
+SPHINXBUILD		= sphinx-build
+SOURCEDIR		= src
+BUILDDIR		= _build
+RUNNER			= cwl-runner
 
 # 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/)
+$(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 https://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
+clean:
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	# Add any other directories to be removed below this line.
 
-watch:
+watch: clean
 	@echo
 	@echo "Building and watching for changes in the documentation."
-	sphinx-autobuild --ignore venv . _build/html
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" \
+			--ignore='**venv' \
+			--ignore='**.github' \
+			--ignore='*.egg-info' \
+			--watch='cwl'
 
-## unittest         : run unit tests on checking tools.
-unittest :
-	@bin/test_lesson_check.py
+## unittest-examples	:
+unittest-examples:
+	cd src/_includes/cwl; cwltest --test=conformance-test.yml --tool=${RUNNER}
 
-#-------------------------------------------------------------------------------
-# Include extra commands if available.
-#-------------------------------------------------------------------------------
+## check-json			:
+check-json:
+	python -m json.tool < src/.zenodo.json >> /dev/null && exit 0 || echo "NOT valid JSON"; exit 1
 
--include commands.mk
+.PHONY: help clean watch unittest-examples check-json Makefile
 
-# Catch-all target: route all unknown targets to Sphinx using the new
+# 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)

CITATION renamed to CITATION.md

@@ -2,7 +2,7 @@
 
 [![Syntax Check](https://travis-ci.org/common-workflow-language/user_guide.svg?branch=main)](https://travis-ci.org/common-workflow-language/user_guide)
 
-[User guide for CWL v1.0.2](https://www.commonwl.org/user_guide/)
+[User guide for CWL v1.2.0](https://www.commonwl.org/user_guide/)
 
 Original source:
 https://github.com/common-workflow-language/common-workflow-language/blob/a2a8a08b8c8d56f8f2ca6284ca4e9cbf23d19346/v1.0/UserGuide.yml
@@ -15,8 +15,77 @@ To edit the user guide:
 
 We'd like to ask you to familiarize yourself with our [Contribution Guide](CONTRIBUTING.md).
 
+### Code examples
 
-* FIXME
+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/).
+
+### 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.
+
+```bash
+$ (venv) myst-anchors basic-concepts.md
+<h1 id="basic-concepts"></h1>
+<h2 id="the-cwl-standard"></h2>
+<h2 id="implementations"></h2>
+<h2 id="cwl-objects-model"></h2>
+```
+
+You can also create reference anchor links anywhere on the page with
+``(test)=``, which can be used in the page as `#test` (these do not appear
+in the `myst-anchor` output).
+
+## Extensions
+
+We use MyST Parser with Sphinx. This gives us the best of both Sphinx and Markdown,
+while also supporting reStructuredText, Sphinx, and MyST extensions.
+
+### String Substitutions
+
+For convenience, we have the currently supported version of the specification as a
+constant in `conf.py`. We have it in two forms:
+
+- Markdown preformatted, i.e. \`v0.0\` which is formatted as `v0.0`
+- Plain text, i.e. v0.0
+
+Note that String Substitutions do not work with links. As workaround, you can use
+string formatting or replacements.
+
+```
+The CWL {{ cwl_version  }} Specification: {{ '<https://www.commonwl.org/{}/>'.format(cwl_version_text) }}
+```
+
+For more:
+
+- <https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2>
+- <https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-and-urls>
+- <https://github.com/executablebooks/MyST-Parser/issues/279>
 
 ## Authors