python-sphinxrestructuredtext

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

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

Solution

  • 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>