Closed mr-c closed 10 months ago
Hello @mr-c , could you please shed more light on this issue? I think it's something I could work on. Thank you!
@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.
@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
@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?
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 :+1:
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.
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 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 :laughing:), 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 :laughing: :+1:
Cheers Bruno
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.
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!
@Mackenzie-OO7 see the linked PR :point_up:
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 :+1:
Done by @Mackenzie-OO7 ; thanks!
Currently we have separate instructions in the user guide, the novice tutorial, the cwltool README, and probably other places