Skip to content

docs: give the WDL quickstart example a version and test it - #5566

Merged
adamnovak merged 1 commit into
DataBiosphere:masterfrom
vshulcz:issues/5534-wdl-quickstart-version
Aug 20, 2026
Merged

docs: give the WDL quickstart example a version and test it#5566
adamnovak merged 1 commit into
DataBiosphere:masterfrom
vshulcz:issues/5534-wdl-quickstart-version

Conversation

@vshulcz

@vshulcz vshulcz commented Aug 16, 2026

Copy link
Copy Markdown
Contributor

Changelog Entry

To be copied to the draft changelog by merger:

  • The WDL quickstart example now specifies a WDL version and is covered by a test.

Description

Fixes #5534.

The WDL in the quickstart has no version, so it is parsed as draft-2 and toil-wdl-runner fails on it:

(Ln 1, Col 1) MissingVersion, document should declare WDL version; draft-2 assumed
WDL.Error.EvalError: Cannot evaluate no expression for message

The inputs JSON also addresses the task input directly (write_simple_file.write_file.message), which does not bind.

This ports the example to WDL 1.0 (input sections, ~{} placeholder, the call passing message through), so the inputs file uses write_simple_file.message.

To keep the docs and a tested file from drifting apart, the example now lives in src/toil/test/docs/scripts/ next to the other documentation examples and is pulled into quickStart.rst with literalinclude. MANIFEST.in already ships that directory. test_documentation_quickstart in wdltoil_test.py runs it the same way test_MD5sum runs its workflow.

Verified locally on an Apple Silicon macOS host with Docker:

$ toil-wdl-runner wdl-helloworld.wdl wdl-helloworld.json -o out --logDebug --retryCount=0
Workflow stopped. Success: True
{"write_simple_file.write_file.test": ".../out/write_simple_file.write_file/wdl-helloworld-output.txt"}
$ cat out/write_simple_file.write_file/wdl-helloworld-output.txt
Hello world!

$ pytest src/toil/test/wdl/wdltoil_test.py -k test_documentation_quickstart -x -q
1 passed, 35 deselected

I left make format alone: black --check already reports wdltoil_test.py as unformatted on unmodified master here, so running it would bury this change in unrelated reformatting.

The example was written in draft-2 style without a version line, so
toil-wdl-runner refused to run it. Move it into
src/toil/test/docs/scripts, port it to WDL 1.0 and include it from the
docs so the quickstart and the tested file cannot drift apart.

Signed-off-by: vshulcz <vshulcz@gmail.com>

@adamnovak adamnovak left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks OK to me.

@adamnovak
adamnovak merged commit 93f1ed1 into DataBiosphere:master Aug 20, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

WDL quickstart example in the documentation lacks a version, so it won't work (and isn't under test)

2 participants