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

Question

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 1

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> 

Answer 2

New, better answer for 2016!

The autosection extension lets you do this easily, with real cross references.

============= Some Document =============   Internal Headline ================= 

then, later...

=============== Some Other Doc ===============   A link-  :ref:`Internal Headline` 

This extension is built-in, so all you need is to edit conf.py

extensions = [     .     . other     . extensions     . already     . listed     .     'sphinx.ext.autosectionlabel', ] 

The only thing you have to be careful of is that now you can't duplicate internal headlines across the doc collection. (Worth it.)