-
-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Document how to set a custom reStructured Text link target name #13576
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
strugee
wants to merge
2
commits into
sphinx-doc:master
Choose a base branch
from
strugee:link-target-custom-text-doc
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What do you mean by 'custom target name'? This is called an 'alias' in the Docutils documentation: https://www.docutils.org/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wrote it that way based on the preceding paragraph:
I wasn't aware of the alias nomenclature - to be honest, largely because I searched "restructured text link syntax" or something like that, and this page was the top result. As someone pretty unfamiliar with the rST world I honestly kind of thought, without having really consciously thought about it, that this was the canonical format documentation. So it didn't even occur to me to check elsewhere.
Knowing this now, I can update the patch (and probably update the preceding sentence at the same time). But I can also see an argument for just saying, this syntax is a little advanced, here's a link to upstream and no example?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think better to provide an example, especially given the PR has already been created.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When giving an example for an embedded alias (custom name), it should include a link to the rST Specification or user documentation.
Also, a custom name does not make much sense in a single-use target. I suggest something in the line:
Note:
also defines a target with reference name "link text". Users that are not aware of this may not understand why a second link with the same name leads to a "duplicate name" error!
For single-use hyperlinks with embedded URI, I strongly recommend anonymous links (with two trailing underscores).
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gmilde Let me drop-in to ask a question if you are available. Recently I edited some text with references to research papers and I added
DOI
links. I got lots of warnings from Docutils because as you commented here targets are defined, and they all share the sameDOI
name. What would be the method here to avoid such Docutils warnings from having added (for HTML output) lots of links all sharing the same (short name)DOI
. My use case (to decorate items in a list of references) sounds legit. Sorry for off-topic.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
An anonymous reference? Eg
DOI__
.Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks @AA-Turner, I now tried multiple
`DOI link`__
and this has indeed solved my problem!I think I had used the syntax before but that this was at a time when I was not aware of the
WARNING: Duplicate explicit target name
one gets when one uses`DOI link <https://.../>`_
multiple times with distinct URLs. By the way I realize now that theWARNING
is emitted only if the URL changes. NoWARNING
if one uses multiple times same URL with same text at various locations.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I realize now in my reST source I had also some
`FOO <A_>`_
and`FOO <B_>`_
syntax with sameFOO
and then<A_>
is resolved by a.. _A: URL
and<B_>
by a.. _B: OTHERURL
and there was no Docutils warning then. So I was pretty much surprised by the warnings caused by`DOI <URL>`_
and`DOI <OTHERURL>`_
which I noticed later. I recall now that I thought about using the same I had earlier in the file withA
versusB
sharing the sameFOO
, but I had other priorities and forgot about it afterwards.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@jfbu this is a code review thread. Is there an action item here for me?