Sphinx: cross-reference indexed item

Question

How can I cross-reference an indexed item inside a reStructuredText document?

For example, how can I cross-reference SectionB:

.. index::
    pair: SectionA; SectionB

SectionB
--------

SectionB description.

I tried using the index labels in references, such as:

:ref:`SectionB`

but this does not work.

Merit

are you really using :ref:'SectionB' instead of :ref:`SectionB` ? you should be using backticks... – Trifacial

I am using backticks, but Markdown uses them as inline code spans so I just changed the example to use '' – Merit

Answer 1

see: Cross-referencing arbitrary locations

in the Sphinx documentation.

I think what you might be missing is a reference label,

Try something like:

.. index::
pair: SectionA; SectionB

.. _section-b-label:

SectionB
--------

SectionB description.

and then elsewhere do:

:ref:`section-b-label`

Trifacial

I know I can use reference labels. What I was trying to avoid is having to add both the index and the reference label. It seems a bit redundant. – Merit

Answer 2

Sphinx (now, since v1.4 in 2016) has an autosectionlabel extension that does exactly what you want:

This extension allows you to refer sections its title. This affects to the reference role (ref).

For example:

A Plain Title
-------------

This is the text of the section.

It refers to the section title, see :ref:`A Plain Title`. 

Internally, this extension generates the labels for each section. If same section names are used in whole of document, any one is used for a target by default. The autosectionlabel_prefix_document configuration variable can be used to make headings which appear multiple times but in different documents unique.

Antetype

Answer 3

This options still does not seem possible without adding in custom labels. There is an issue open at https://github.com/sphinx-doc/sphinx/issues/1671

It is possible to link to glossary terms using :term:, and index links ideally would be possible and added to the arbitrary links docs

Lanky