Document how to set a custom reStructured Text link target name

[strugee]

Purpose

Basically what the title says. AFAICT this isn't documented (if it is, it isn't clear/I couldn't find it). E.g. this caused me a lot of grief in pallets/flask#5737.

Note that I ignored the contributing guide's instructions to preview the HTML locally, because this change is so simple and I didn't want to bother setting up a dev environment. I did, however, verify that the change looked valid in the GitHub web interface (including putting the example fragment in a new file to make sure it actually rendered).

References

N/A

[AA-Turner]

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

[strugee]

I wrote it that way based on the preceding paragraph:

You can also separate the link and the target definition [...]

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?

[AA-Turner]

I think better to provide an example, especially given the PR has already been created.

[gmilde]

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:

You can also separate the link and the *target definition* 
(:duref:`ref <hyperlink-targets>`), like this::

    This is a paragraph that contains `a link`_.

    .. _a link: https://example.org/

The target can be reused::

    This is another paragraph that contains `a link`_.

If you want a different link text, use an *embedded alias* 
(:duref:`ref <embedded-uris-and-aliases>`)::

    This paragraph contains `another link 
    to the same target <a link_>`_.

Note:

  `Link text <https://domain.invalid/>`_

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).

[jfbu]

@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 same DOI 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.

[AA-Turner]

An anonymous reference? Eg DOI__.

[jfbu]

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 the WARNING is emitted only if the URL changes. No WARNING if one uses multiple times same URL with same text at various locations.

[jfbu]

I realize now in my reST source I had also some `FOO <A_>`_ and `FOO <B_>`_ syntax with same FOO 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 with A versus B sharing the same FOO, but I had other priorities and forgot about it afterwards.

[strugee]

@jfbu this is a code review thread. Is there an action item here for me?

[AA-Turner]

@strugee FYI you may use the automatic PR previews: https://sphinx--13576.org.readthedocs.build/en/13576/usage/restructuredtext/basics.html#external-links

A

[gmilde]

Am 24.05.25 schrieb Adam Turner:

@AA-Turner commented on this pull request.
An anonymous reference? Eg DOI__.

Yes.
To be more precise, an anonymous link like

a link with `a custom target name <custom_>`__.

is a compact equivalent to the combination of an anonymous reference and anonymous indirect target:

a link with `a custom target name`__.

__ custom_

However, with single trailing underline like

a link with `a custom target name <custom_>`_.

it is a named reference with embedded target, a compact equivalent to

a link with `a custom target name`_.

.. _a custom target name: custom_

conclusion:

• Use a single trailing underline if you want to re-use the link text in references to the same target.
• Use a double trailing underline if you want to re-use the link text in references to a different target.