Document more features of cwltool

[kinow]

Partially addresses #166

• cwltool --make-template
• cwltool --cachedir

For --make-template, I added a small paragraph to the Inputs section.

For --cachedir, I couldn't decide among prerequisites, FAQ, and a new section. In the end due to its length, I thought it would fit better in a new section for Troubleshooting (I imagine other devs have other interesting ways to troubleshoot CWL & cwltool execution). But happy to move it to somewhere else too.

[kinow]

@mr-c, @tetron could you take a quick look before I continue working on this one?

For the --make-template, I think it fit well with the “Inputs” section https://common-workflow-languageuser-guide--246.org.readthedocs.build/en/246/topics/inputs.html#inp-job-yml (see the "Note" below the example linked).

For --cachedir, I created a separate “Troubleshooting” section: https://common-workflow-languageuser-guide--246.org.readthedocs.build/en/246/topics/troubleshooting.html#run-cwltool-with-cachedir

But I cannot find a good place in the existing sections for --parallel and --singularity. For --singularity I thought about an entry we have in the FAQ for CWL+singularity, https://common-workflow-languageuser-guide--246.org.readthedocs.build/en/246/faq.html#use-cwl-and-cwltool-with-singularity.

But still not sure if that's the best place to document the cwltool --singularity option.

Any thoughts?

Thanks!

[mr-c]

for --parallel, that can be introduced as soon as there are steps that can be run independently

for --singularity & --podman, that can be introduced the first time we have a DockerRequirement; possibly users might want use CWLTOOL_OPTIONS to always set these options

[kinow]

Leaving the issue open, and partially addressing it with this PR 👍

[mr-c]

@kinow ; now that #248 is merged, can you use the same technique here?

[kinow]

@kinow ; now that #248 is merged, can you use the same technique here?

Done. I believe I replaced all code blocks for commands with runcmd 👍 Thanks @mr-c

[mr-c]

I don't see any effect of emphasize-lines with {runcmd}, alas (or at least, not on Read The Docs)

[kinow]

You arr correct. I actually had seen it and forgot to log an issue for that.

Runcmd extends the code block directive. It runs a command and then renders the code block.

It looks like the emphasize is applied before the code is rendered. So it gets ignored instead of highlighting the rendered command.

A bit tricky but I guess it could be one of those 1-line code fixes (that alas you spend more than you wanted on it 😅 )