Search code examples
python-sphinxrestructuredtext

Restructured text (rst) http links underscore ('__' vs '_' use)

With restructured text, I've seen both these used:

`Some Link <http://www.some.com>`_
`Some Link <http://www.some.com>`__

Both generate the same output from Sphinx,

Whats the difference between using _ or a double underscore __ for http URL links?

Why would you one over another?

Solution

  • In short, if its a one-off (anonymous) URL which you don't intend to reference, use double underscore.

    In practice you could use either in most cases, they generate the same HTML output for example.

    However, using single underscores for links means that by default you're creating a reference target - which could conflict with other references of the same name.

    So this for example will warn:

    .. _Thing:

Title
=====

Text with `Thing <http://link.com>`_.

    WARNING: Duplicate target name, cannot be used as a unique reference: "thing".

    While this could be overlooked in most cases, it could make for confusing situations especially for anyone inexperienced with reStructuredText. So you may prefer to avoid this entirely only defining targets when that is your intention.

    According to: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks

    With a single trailing underscore, the reference is named and the same target URI may be referred to again. With two trailing underscores, the reference and target are both anonymous, and the target cannot be referred to again. These are "one-off" hyperlinks.

    There are examples on the page links.