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]

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