Ответ 1

Игнорировать этот ответ, он не работает: лучше использовать ответ от Louis

Для привязки вы можете определить "короткие" имена привязок следующим образом:

.. _ShortAnchor:

Target Header goes here
=======================

Some text.

Чтобы ссылаться на этот заголовок, используйте:

For more details, see ShortAnchor_.

Обратите внимание, что это даже расширяет ShortAnchor до полного имени заголовка.

Вы также можете использовать полное имя заголовка, например:

See `Target Header goes here`_ chapter.

Но это больше подвержено ошибкам изменения текста заголовка.

Все это работает в нескольких исходных файлах, являющихся частью одной окончательной документации.

Ответ 2

Выражение "reST/Sphinx" делает проблему неясной. Это о reStructuredText вообще и Sphinx, или только о reStructuredText, как используется в Sphinx (а не в реструктурированном тексте вообще)? Я расскажу об обоих, так как люди, использующие RST, скорее всего, столкнутся с обоими случаями:

Sphinx

Помимо директив для домена, которые могут использоваться для связи с различными объектами, такими как классы (:class:), существует общая директива :ref:, документированная здесь. Они приводят этот пример:

    .. _my-reference-label:

    Section to cross-reference
    --------------------------

    This is the text of the section.

    It refers to the section itself, see :ref:`my-reference-label`.

Хотя общий механизм гиперссылки, предлагаемый RST, работает в Sphinx, в документации рекомендуется использовать его при использовании Sphinx:

Использование ref рекомендуется для стандартных ссылок reStructuredText для разделов (например, Section title _), поскольку оно работает с файлами, когда заголовки разделов изменены и для всех разработчиков, которые поддерживают перекрестные ссылки.

RST, в целом

У инструментов, которые конвертируют RST файлы в HTML, необязательно есть понятие коллекции. Это, например, если вы полагаетесь на github для преобразования RST файлов в HTML или если вы используете инструмент командной строки, например rst2html. К сожалению, различные способы использования желаемого результата зависят от того, какой инструмент вы используете. Например, если вы используете rst2html и хотите, чтобы файл A.rst ссылался на раздел с именем "Раздел" в файле other.rst и вы хотите, чтобы последний HTML работал в браузере, тогда A.rst будет содержать:

`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.

Вам нужно связать с окончательным HTML файлом, и вам нужно знать, что будет в id для данного раздела. Если вы хотите сделать то же самое для файла, поданного через github:

`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.

Здесь также вам нужно знать id, приведенный в разделе. Однако вы ссылаетесь на RST файл, потому что только при доступе к RST файлу создается HTML-код. (На момент написания этого ответа доступ к HTML напрямую запрещен.)

Полный пример доступен здесь.

Ответ 3

Новый, лучший ответ на 2016 год!

Расширение autosection позволяет вам сделать это легко.

=============
Some Document
=============


Internal Headline
=================

затем, позже...

===============
Some Other Doc
===============


A link-  :ref:`Internal Headline`

Это расширение встроено, поэтому вам нужно только отредактировать conf.py

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

Единственное, что вам нужно быть осторожным, это то, что теперь вы не можете дублировать внутренние заголовки в коллекции документов. (Стоит это.)