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.
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/>`_.
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?
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.
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.
To state the options for the original question: How to get
<a href="http://some.url">blah</a>
Simple named hyperlink:
Use a simple hyperlink reference and target. The target can be used for more than one reference to the same URI.
How to get blah_.
.. _blah: http://some.url
Named hyperlink with special chars or multiple words: Use a phrase reference and target. The target can be used for more than one reference to the same URI.
`How to get blah`_.
.. _How to get blah: http://some.url
If a long link text is used just once or if the same link text is used for links to different URIs: Use an anonymous hyperlink (you need one target for every reference):
How to get blah__ or `how to get blah`__.
And now for something completely different (blah__).
__ http://some.url
__ http://some.url
__ https://another.url
Keep reference and target in one place: Use an embedded URI (named or anonymous).
`How to get blah <http://some.url>`_.
How to get `blah <http://some.url>`__.
A reference with custom link text to an existing named target: Use an embedded alias (named or anonymous).
`How to get blah <blah_>`__.
.. _blah: http://some.url
