How to make an internal link to a heading in sphinx restructuredtext without creating arbitrary labels?

caduceus picture caduceus · Sep 5, 2013 · Viewed 15.9k times · Source

I have a document with many headings and sub-headings. Further into the text I want to link back to one of the headings. How can I do this without the redundancy of :ref: labels? The contents seems to pick up headers just fine. I was hoping for something like this: `#polled-data-retrieval`_.

Answer

Chris picture Chris · Sep 9, 2013

reStructuredText supports implicit hyperlink targets. From the reStructuredText quick reference:

Section titles, footnotes, and citations automatically generate hyperlink targets (the title text or footnote/citation label is used as the hyperlink name).

So the following text (lifted from the reStructuredText quick reference, spelling mistakes and all):

Titles are targets, too
=======================
Implict references, like `Titles are targets, too`_.

produces HTML similar to the following:

<strong><a name="title">Titles are targets, too</a></strong>

<p>Implict references, like <a href="#title">Titles are targets, too</a>.</p>