Як вставити перехресне посилання на сторінку 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 рік!

Розширення автосекції дозволяє вам це зробити легко.

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


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

потім, пізніше ...

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


A link-  :ref:`Internal Headline`

Це розширення є вбудованим, тому все, що вам потрібно - це редагувати conf.py

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

Єдине, на що потрібно бути обережним - це те, що тепер ви не можете копіювати внутрішні заголовки в колекції doc. (Варто.)

Приклад:

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

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

Для цього використовується функція автоматичного вибору , тому її потрібно буде відредагувати config.pyтаким чином:

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