Sphinx: Duplicate explicit target name errors

[barbara-sfx]

Subject: Getting "Duplicate explicit target name" errors

Problem

• I have links to several pages; the text for each link is the same: "Details". I am getting errors that 1) show the text as lower case, which is confusing; 2) show a random line number; and 3) should not be occurring at all.

Procedure to reproduce the problem

make clean html

Error logs / results

/Users/barbara/Documents/filenamet.rst:25: WARNING: Duplicate explicit target name: "details".
/Users/barbara/Documents/filenamet.rst:25: WARNING: Duplicate explicit target name: "details".

Expected results

No errors

Reproducible project / your project

Add lines like these to your file:

-  `Details <https://github.com/signalfx/integrations/tree/release/collectd>`_
-  `Details <https://github.com/signalfx/integrations/tree/release/collectd-docker>`_
-  `Details <https://github.com/signalfx/integrations/tree/release/signalfx-metadata>`_

Environment info

• OS: Mac 10.11.6
• Python version: 2.7.10
• Sphinx version: 1.6.3

[tk0miya]

Unfortunately, it is a part of spec of reST.
docutils; the reference implementation of reST utilities also behaves as same:

$ cat details.rst
-  `Details <https://github.com/signalfx/integrations/tree/release/collectd>`_
-  `Details <https://github.com/signalfx/integrations/tree/release/collectd-docker>`_
-  `Details <https://github.com/signalfx/integrations/tree/release/signalfx-metadata>`_

$ rst2html.py details.rst > /dev/null
details.rst:1: (WARNING/2) Duplicate explicit target name: "details".
details.rst:1: (WARNING/2) Duplicate explicit target name: "details".

Please use anonymous reference instead:

$ cat details.rst
-  `Details <https://github.com/signalfx/integrations/tree/release/collectd>`__
-  `Details <https://github.com/signalfx/integrations/tree/release/collectd-docker>`__
-  `Details <https://github.com/signalfx/integrations/tree/release/signalfx-metadata>`__

use double underscores ``__`` to make references here!

$ rst2html.py details.rst > /dev/null
# => No warnings

[barbara-sfx]

Double underlines - ya gotta love it! Thanks for the response.

This is right up there with requiring a space after the text and before the < of the URL. When I was first learning RST I pulled my hair out trying to figure out why none of my links worked! That will be my next request to change, when I get around to it.

[tk0miya]

It would be nice if some lint tool is given :-)

[cgay]

I was unable to find anything about "anonymous references" in the Sphinx docs. If anyone reads this I would appreciate a pointer. This seems like a pretty easy issue to run into so I expected to see it mentioned here: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks

[tk0miya]

Please read the specification of reST markup.
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks

As you said, it would be nice if our document describes all of reST syntax perfectly!