Use anonymous references for links with embedded URLs #13615
Conversation
timhoffm
force-pushed
the
doc-external-links
branch
from
b0ff0f7 to
bd1adac
Compare
There was a problem hiding this comment.
LGTM with nits.
There is one more syntax but it would be confusing to state it here. It is `Link text <goto_>`__, with the .. _goto: standing after the paragraph. As I reported at #13576 (comment), with Docutils 0.21.2, even with a single underscore one could use this with identical Link text e.g. See `DOI <goto1_>`_ or `DOI <goto2_>`_ without Docutils raising warnings but this is no more true since Docutils r10151.
AA-Turner
changed the title
|
cc: @gmilde |
timhoffm
force-pushed
the
doc-external-links
branch
from
bd1adac to
02cc1df
Compare
|
Thanks @timhoffm, I wasn't aware of the single vs. double underscore issue. For reference, and in case anybody is wondering (as I was), I tried it (with Sphinx When I use multiple embedded URLs with the same link name "link" and identical URLs, everything works as expected and there are no warnings. When I use different URLs with the same name (and with a single underscore), it still works fine, and the links point to the correct URLs, but I'm getting these messages. Using two underscores made the messages go away. And another thing: what about "anonymous hyperlinks" as described here: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks? I like using those but they don't seem to be mentioned on the Sphinx doc page (https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). Are they discouraged for some reason? If not, I think it would be great to add them to the docs! |
| This is a paragraph that contains `a link`_. | ||
|
|
||
| .. _a link: https://domain.invalid/ |
There was a problem hiding this comment.
If I'm not mistaken, the exact same example is repeated below the inserted text, now it appears two times on the page.
Is this intentional?
There was a problem hiding this comment.
It is rather a leftover from the last edit.
See my comment at #13613 (comment)
|
@mgeier happy to look at a PR that adds a mention of the |
Closes #13613.
The explanation got a bit longer than I would have liked. But I think it's important to make people aware that they should use two underscoes even though one may also work. And if we do that, we need to briefly explain the difference.