In one of my Sphinx files, I have this :
.. _pyjnius:
Pyjnius
=======
When running on Android, a version of the `Pyjnius <https://pyjnius.readthedocs.io/en/stable/>`_
library is available. This allows advanced creators to call into the Android
libraries.
It seems to compile just how I want it to, but I get a warning saying that WARNING: Duplicate explicit target name: "pyjnius". I got to this issue, advising to end the link with two underscores rather than one, and that it's called an anonymous link. It's not the exact same problem: in the issue there's two links with the same name, and in my case there's only one link, but I tried the solution and it works.
What are the differences between `this <link>`_ and `that <link>`__, aka between anonymous and non-anonymous links ? What would happen if I convert all my external hyperlinks to the double-underscore syntax ?
What are the differences between (...) between anonymous and non-anonymous link
A reference name is created when you declare a hyperlink target. But if the target is anonymous the name isn't used to match the reference to its target. The following quote from the docs sums it up:
The reference name of the reference is not used to match the reference to its target. Instead, the order of anonymous hyperlink references and targets within the document is significant: the first anonymous reference will link to the first anonymous target. The number of anonymous hyperlink references in a document must match the number of anonymous targets.
Now the second part of the question that was embedded in the same sentence:
What are the differences between
`this <link>`_and`that <link>`__
If you read the reStructuredText specification carefully, no clear example of the concise `Title <Link>`_ syntax is given, but it's an external hyperlink target (because the URL points to the exterior of your documentation). What happens is that the Title acts as the reference name for the target, hence the verbatim error: "Duplicate explicit target name".
Making the declaration of the hyperlink target anonymous by using the double underscore __ causes Title not to be used as the target name, thus there's no longer a duplicate target name because order of declaration is used to match the anonymous target to the link.
In conclusion:
and in my case there's only one link
Yes, but what the error message is saying is that there's a "Duplicate explicit target name" the problem is that Pyjnius is declared as a target once above the section, and again explicitly as the title (acting as target name) in the link using the shortened syntax.
Also note that the reference names (the target, or title) is normalized and thus case insensitive. Thus in your example the name Pyjnius <URL> ends up being normalized to pyjnius which is the same target name above the section.
- case is normalized (all alphabetic characters are converted to lowercase).