consolidate the cwltool installation guidance at cwltool.readthedocs.io/

[mr-c]

Currently we have separate instructions in the user guide, the novice tutorial, the cwltool README, and probably other places

[dear-ore]

Hello @mr-c , could you please shed more light on this issue? I think it's something I could work on. Thank you!

[swzCuroverse]

@Mackenzie-OO7 is going to look at this.

I think the best bet would be to first look at what is in the CWL User Guide for installing cwltool vs cwltool.readthedocs.io -- and if there is anything missing in cwltool.readthedocs.io add it and then just link to it. I think you can in sphinx/rtd import sections which is nicer than a link out to the install, if that is possible.

[swzCuroverse]

@Mackenzie-OO7

You said that it was already set. But it looks like the user guide does not yet link to cwltool.readthedocs and has a bunch of install stuff that needs to be removed still -

See here: http://www.commonwl.org/user_guide/introduction/prerequisites.html#cwl-runner

[Mackenzie-OO7]

@kinow Hi, I'm trying to link to https://cwltool.readthedocs.io/en/latest/#install with Intersphinx. I added intersphinx to the list of extensions in the conf.py file, and used intersphinx_mapping configuration to add a name and link. After cross-referencing, it doesn't seem to be working. Do you have any suggestions on what I could do?

[kinow]

Hi @Mackenzie-OO7

I added intersphinx to the list of extensions in the conf.py file, and used intersphinx_mapping configuration to add a name and link.

No warning or error messages in the log when you build the sphinx site?

Do you have any suggestions on what I could do?

I can take a look if you have a branch somewhere with your changes 👍

[Mackenzie-OO7]

Hi @Mackenzie-OO7

I added intersphinx to the list of extensions in the conf.py file, and used intersphinx_mapping configuration to add a name and link.

No warning or error messages in the log when you build the sphinx site?

Do you have any suggestions on what I could do?

I can take a look if you have a branch somewhere with your changes 👍

Nope, no error or warnings. Thanks! Here's the branch I made changes to.

[mr-c]

Intersphinx is nice when you are likely to make many links to another Sphinx site. For a single link, it isn't necessary; in that case use a regular URL link.

[kinow]

Thanks for the link @Mackenzie-OO7

Nope, no error or warnings.

Building from your branch, I get the following in my logs for make watch:

/home/kinow/Development/python/workspace/user_guide/src/introduction/prerequisites.md:50: WARNING: unknown document: 'cwltool:install'

I did as they mention in the intersphinx docs to print the available links: (venv) kinow@ranma:~/Development/python/workspace/user_guide$ python -m sphinx.ext.intersphinx https://cwltool.readthedocs.io/en/latest/objects.inv

Looking at the output of the command above, I see std:doc, which you used correctly in your change.

Visit the `cwltool` {doc}`documentation <cwltool:install>

But the install is nowhere in the output. I had a look at the cwltool website, and I think installation is an anchor: https://cwltool.readthedocs.io/en/latest/#install

I believe here's the issue right now. The cwltool website is not generating links for the anchors. I think we can fix it by adding autosectionlabel to cwltool. I'll create a PR there and link to this PR.

Sphinx logs pretty much everything in warn/error. There are a few markdown errors that may be hidden, but for that case you can run the sphinx-build command (which is executed when you run make - see Makefile) with the -vvv to show more logs.

Most of the time I find what's wrong by looking at the Sphinx logs. But... when I cannot find anything (and that happens a lot to be honest 😆), normally I open a book and read a couple pages, walk outside, and when I look at the logs again I find the warn/error logs that I was looking for 😆 👍

Cheers
Bruno

[Mackenzie-OO7]

Intersphinx is nice when you are likely to make many links to another Sphinx site. For a single link, it isn't necessary; in that case use a regular URL link.

Thanks for the clarification.

[Mackenzie-OO7]

I believe here's the issue right now. The cwltool website is not generating links for the anchors. I think we can fix it by adding autosectionlabel to cwltool. I'll create a PR there and link to this PR.

Thank you so much!

[kinow]

@Mackenzie-OO7 see the linked PR ☝️

After that's merged (assuming it will be merged), you will need to change your branch:

diff --git a/src/introduction/prerequisites.md b/src/introduction/prerequisites.md
index a5b1bb3..2341b45 100644
--- a/src/introduction/prerequisites.md
+++ b/src/introduction/prerequisites.md
@@ -47,7 +47,7 @@ current CWL specification, {{ cwl_version }}.
 like `venv` or `conda`.
 
 ```{note}
-Visit the `cwltool` {doc}`documentation <cwltool:install>`
+Visit the `cwltool` {ref}`documentation <cwltool:index:install>`
 for details on installing `cwltool`.
 ```
 Let's use a simple CWL tool description `true.cwl` with `cwltool`.

Cheers

EDIT: @Mackenzie-OO7 I've updated the diff above... I've enabled the auto-prefix feature of autosectionlabel. So now we need to include the file name (e.g. index) in the link 👍

[mr-c]

Done by @Mackenzie-OO7 ; thanks!