Как вставить перекрестную ссылку на страницу reST / Sphinx в подзаголовок или привязку на другой странице в том же наборе документации?

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

Сфинкс

Помимо доменных директив, которые можно использовать для связывания с различными объектами, такими как классы ( :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, потому что HTML создается только при доступе к файлу RST. (На момент написания этого ответа прямой доступ к HTML запрещен.)

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

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

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

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


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

тогда позже...

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


A link-  :ref:`Internal Headline`

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

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

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

Пример:

Hey, read the :ref:`Installation:Homebrew` section.

где Homebrewнаходится раздел внутри другого документа с именем Installation.rst.

Здесь используется функция автоматического разделения , поэтому необходимо будет отредактировать config.pyследующее:

extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True