How to make an internal link to a heading in sphinx restructuredtext without creating arbitrary labels?
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>
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.)
A small addition to the answer by Chris:
If you want to link to headings without using the exact name of that heading for the link, you can do it like this:
Titles are targets, too
=======================
See `here <#titles-are-targets-too>`_
This will render as:
<h1 id="titles-are-targets-too">Titles are targets, too</h1>
<p>See <a href="#titles-are-targets-too">here</a></p>