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.

Uppermost

Answer 1

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/>`_.

Uppermost

How about multiple words in the link text? – Vomiturition

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

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. – Vomiturition

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). – Ebb

@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 – Carin

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

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

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. – Insensible

I cannot for the life of me get this to work with a "named" reference using the syntax Stack Overflow home <SO>. I even copied and pasted this exact code! It just constructs a relative path to the current docs file, with SO at the end. Has this syntax been removed in recent versions? – Elisaelisabet

@Elisaelisabet I made it work. See my answer. – Brooklet

Answer 2

This has been very frustrating, but I tracked down a solution as of mid-2023.

Presently, the fashion something called `"work-stealing" <BL94_>`_.

and later...

.. _BL94: http://supertech.csail.mit.edu/papers/steal.pdf

Note the two underscores: once inside the angle brackets, and once after the closing grave-accent. (Back-quote, if you're younger than the internet.) This correctly links the text "work-stealing" to the PDF article.

Brooklet

This is almost good, but you should use two underscores rather than one. I expanded on it in my own answer (would've posted a comment but couldn't figure out the proper inline syntax). – Waterside

Just had this exact problem and this solution worked for me. – Spock

Answer 3

A modification of Ian's answer:

Presently, the fashion something called `"work-stealing" <BL94_>`__.
and later...

.. _BL94: http://supertech.csail.mit.edu/papers/steal.pdf

The difference is that you should use two underscores at the end, rather than one.

This is because according to the spec, these are exactly equivalent:

`blah <foo>`_     <- only one underscore!

`blah`_

.. blah: foo

So the example with one underscore will generate a target for "work-stealing" as well, which is likely not what is desired.

Using two underscores will create an anonymous reference instead, which won't result in a separate new target.

Waterside

Answer 4

To state the options for the original question: How to get

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

Simple named hyperlink:

How to get blah_.

.. _blah: http://some.url

Named hyperlink with special chars or multiple words:

`How to get blah`_.

.. _How to get blah: http://some.url

Anonymous hyperlink (you need one link target for every reference):

How to get blah__ or
`How to get blah`__.

__ http://some.url
__ http://some.url

Embedded href (named and anonymous):

`How to get blah <http://some.url>`_.
How to get `blah <http://some.url>`__.

Embedded alias: (can be named or anonymous)

`How to get blah <blah_>`__.

.. _blah: http://some.url

Intertexture