42

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.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Anton Arhipov
  • 6,479
  • 1
  • 35
  • 43

2 Answers2

68

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/>`_.
Mateen Ulhaq
  • 24,552
  • 19
  • 101
  • 135
Anton Arhipov
  • 6,479
  • 1
  • 35
  • 43
  • 3
    How about multiple words in the link text? – Michael Goerz Nov 22 '17 at 19:47
  • @MichaelGoerz in the second example, it contains multiple words in the link text, doesn't it? – Anton Arhipov Nov 23 '17 at 11:30
  • 5
    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: http://stackoverflow.com". It's not in the documentation. – Michael Goerz Nov 24 '17 at 04:36
  • 2
    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). – Ove Mar 24 '18 at 11:36
  • @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 – Dushyant Joshi Jul 11 '19 at 10:44
  • Can we decorate the link text (eg: use verbatim) with [this trick](https://stackoverflow.com/a/59007450/420867) – drevicko Jul 10 '20 at 00:21
  • be aware, without the 'http://' or 'https://' it was treating mine as internal links! – Kermit Nov 30 '20 at 15:35
  • 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. – Asmoox Dec 07 '20 at 17:19
  • 5
    I cannot for the life of me get this to work with a "named" reference using the syntax `Stack Overflow home `. 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? – shadowtalker Oct 13 '22 at 20:09
  • @shadowtalker I made it work. See my answer. – Ian Jul 26 '23 at 03:30
1

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.

Ian
  • 4,421
  • 1
  • 20
  • 17