CODEWITHSUNDEEP
hyperlinkpython-sphinxrestructuredtext
Anton Arhipov
Anton Arhipov

Reputation: 6591

Generating an external link in Sphinx

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.

Upvotes: 47

Views: 38941

Answers (4)

G. Milde
G. Milde

Reputation: 862

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

Upvotes: 1

Emily
Emily

Reputation: 2684

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.

Upvotes: 4

Beth
Beth

Reputation: 4660

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.

Upvotes: 8

Anton Arhipov
Anton Arhipov

Reputation: 6591

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

Upvotes: 73

Related Questions