Sphinx is a great tool for developers who want to write nice documentation about their software. I actually use it also to take notes or write about other stuff.
From time to time I have a warning such as :
index.rst:2 WARING: Duplicate explicit target name: "github" |
This is a bit annoying since, the information is a bit parse. Here, I am told that on line 2 there is a duplicated name… Yet, on line 2 there is no mention of github or target name. The tool is great, again, but sometimes a bit cryptic and to be honest since it relies on restructured text syntax (docutils), the warning is sometimes related to the underlying syntax, not sphinx itself.
Looks like this is the case here.
Consider this code::
TEST ==== :Source: See `source <https://github.com/sequana/sequana/>`_. :Issues: Please fill a report on `github <https://github.com/sequana/sequana/issues>`_ To join the project, please let us know on `github <https://github.com/sequana/sequana/issues/306>`_. |
Note the syntax first:
`github <https://github.com/sequana/sequana/issues>`_ |
This code (back quotes) indicates a link. The first word (github) is what will appear in the HTML content.
Then, the link follows (surrounded by less than and greater than characters). The final _ underscore character is part of the syntax.
If you compile this code with sphinx (e.g. version 3.0.1), you will get a warning
`github <https://github.com/sequana/sequana/issues>`_ |
but not for the first link. So, indeed the duplicated link to the same word raise the warning.
How to avoid this warning ? Very simple: duplicate the underscore at the end of the link:
:Source: See `source <https://github.com/sequana/sequana/>`_. :Issues: Please fill a report on `github <https://github.com/sequana/sequana/issues>`__ To join the project, please let us know on `github <https://github.com/sequana/sequana/issues/306>`__. |
