Generating an external link in Sphinx

Question

I'd like to link to some URL in my Sphinx docs:

<a href="http://some.url">blah</a>

I have found something similar in the docs: http://sphinx-doc.org/ext/extlinks.html - but it is rather about replacing the custom syntax with the link, by convention. Instead, I just want to generate a link to external web resource.

Solution

See the reStructuredText documentation. It can be done either with a named reference:

Test hyperlink: SO_.
    
.. _SO: https://stackoverflow.com/

Or with:

Test hyperlink: `Stack Overflow home <SO>`_.
    
.. _SO: https://stackoverflow.com/

Or with an embedded URI:

Test hyperlink: `Stack Overflow home <https://stackoverflow.com/>`_.

Comments

[Michael Goerz]

How about multiple words in the link text?

[Anton Arhipov]

@MichaelGoerz in the second example, it contains multiple words in the link text, doesn't it?

[Michael Goerz]

Yes, but for the case of the named reference, it took me quite a while to figure out that the correct syntax is "` Stack Overflow_ `" (without the spaces -- can't properly format this in a comment) and then " .. _Stack Overflow: stackoverflow.com". It's not in the documentation.

[Ove]

I think the documentation does say that you can put the text in backquotes (with the underscore outside), i.e. `Stack Overflow`_, but it's shown in the "inline markup" section of the quick reference, not in the hyperlinking section (unless you check the specification itself).

[Dushyant Joshi]

@AntonArhipov, is it possible to append string to href like /docs/Orders.html instead of docs/Orders.html? I m very much new to python

[drevicko]

Can we decorate the link text (eg: use verbatim) with this trick

[Kermit]

be aware, without the 'http://' or 'https://' it was treating mine as internal links!

[Asmoox]

How to add many links with the first method? I try different ways with double dots before every URL definition or not, but PyCharm keeps ignoring it.