Добавление перекрестной ссылки на подзаголовок или привязку на другой странице


Ответы:


207

Выражение «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 запрещен.)

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


9
Намного лучший ответ, чем тот, который принял владелец вопроса. (Несмотря на то, что это RST, in Generalбыли неутешительные новости!)
dlm 06

1
Недостатком .. _my-reference-label:подхода Sphinx является то my-reference-label, что URL-адрес отображается после #ссылки. Поэтому нужно использовать красивые названия ярлыков. Кроме того, TOC всегда создает #-ссылку на Section to cross-reference, и, таким образом, #получается две разные -ссылки на один и тот же раздел.
st12 06

4
И если вы хотите дать своей ссылке другое имя, вы всегда можете использовать:ref:`Link title <lmy-reference-label>`
HyperActive

53

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

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

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


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

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

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


A link-  :ref:`Internal Headline`

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

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

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


5
Поскольку я написал этот ответ, я на практике обнаружил пару проблем с этим подходом. Во-первых, переименование раздела - проблема. Во-вторых, у вас часто есть короткие заголовки разделов, такие как «Узнать больше» или «Обзор», которые вы хотите использовать, чего вы не можете, если делаете это. Решение: добавить заголовок раздела при / при переименовании; добавьте заголовок раздела для коротких заголовков раздела (например, _page-title-learn-more). Это немного раздражает, но мне все еще нравится в основном полагаться на автосекцию.
Адам Майкл Вуд

12
Sphinx 1.6 представляет autosectionlabel_prefix_documentопцию конфигурации, которая позволяет избежать проблемы с дублированием заголовка, добавляя к каждой метке раздела префикс имени документа, из которого он взят.
PMOS

2
Это лучшее решение. А заголовок ссылки можно легко изменить с помощью :ref:`Link title <Internal Headline>`. Кроме того, вы можете напрямую ссылаться на страницу (например, quickstart.rst) с помощью:doc:`quickstart`
HyperActive

5

Пример:

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

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

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

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

В 2.0.0b1 они добавлены autosectionlabel_maxdepth, поэтому для работы autosectionlabel вы должны установить для этой переменной значение> = 2. Кроме того , если документы формируются в подпапку, как html, вы должны префикс рефов с его именем: :ref:'html/Installation:Homebrew'. По этой причине вы можете выбрать какое-нибудь общее имя каталога, например generated, чтобы сделать ссылки менее странными при использовании с форматами, отличными от HTML. Из-за этого вы можете 'Homebrew <Installation.html#Homebrew>'__использовать правильный reST и не быть привязанным к Sphinx.
Пагсли,

html/Приставка мне не понадобилась
Крис
Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.