Как я могу связать / сослаться на другой файл reST в документации?

Я просто не знаю, как связать другой документ в файле reST.

Я хочу связать файл с именем install.rst с моим кратким руководством в абзаце. Я не знаю, как мне этого добиться.

Не могли бы вы также обратиться к отличному ресурсу, где я могу найти синтаксис для отдыха. Быстрый старт по умолчанию немного утомителен и не требует подробного обсуждения использования отдыха со сфинксом.

Рассматриваемый документ: http://todx.rtfd.io


python-sphinx read-the-docs restructuredtext
person Aditya ultra    schedule 31.05.2016    source источник

Ответы (6)


arrow_upward
56
arrow_downward

Для создания ссылок между различными файлами reStructuredText (.rst) вы можете использовать встроенную разметку, предоставляемую sphinx. См. документацию под заголовком Документы с перекрестными ссылками

поверх файла вы определяете его метку

.. _my-reference-label:

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

:ref:`my-reference-label`.

Я не считаю, что вам нужно использовать расширение intersphinx, поскольку оно предназначено для связи между разными проектами. С помощью этого метода вы можете связывать разные файлы .rst, используя их относительные пути, как описано в ссылке выше в документации.

person Ryszard Cetnarski    schedule 14.04.2017
comment
При использовании метки она должна быть :ref: вместо :doc:. С :doc: вам нужно будет указать имя другого файла вместо метки. - person luator; 17.04.2018
comment
Я категорически не рекомендую это решение: ни один элемент, кроме начального комментария, не должен предшествовать заголовку документа, потому что многие средства визуализации полагаются на это. Ярлык в начале документа может, например, закручивать навигационные ссылки вашей темы sphinx. Кроме того, ответ слишком конкретен, когда вопрос заключается в том, как создать ссылку на документ, а не на случайное место в документе. - person Jeyes Unterwegs; 12.02.2021
comment
Метка / цель заголовка не обязательно должна быть вверху страницы. Фактически у вас может быть несколько файлов в файле, например по одному для каждого раздела, чтобы вы могли напрямую ссылаться на него. Я считаю, что принято размещать его непосредственно перед заголовком (например, заголовком или заголовком раздела), см. docs.readthedocs.io/en/stable/guides/. - person Sybille Peters; 20.02.2021

arrow_upward
43
arrow_downward

Я пишу ссылку на другой документ, используя это:

:doc:`my document <../my_doc>`

../my_doc - это путь к моему my_doc.rst файлу.

У меня также есть расширение inter-sphinx в моем conf.py файле.

extensions = ['sphinx.ext.intersphinx']
person Eme Eme    schedule 29.05.2018
comment
Расширение intersphinx не требуется, если вы ссылаетесь на документы в том же проекте. - person Padix Key; 11.09.2019

arrow_upward
25
arrow_downward

Упростив ответ @ eme-eme, вы можете просто сделать:

:doc:`path/to/document`

Вам не нужно заключать путь в ‹> и предоставлять текст для отображения. В этом случае заголовок верхнего уровня из указанного документа будет отображаться как ссылка.

Для этого вам не нужно расширение inter-sphinx.

person michcio1234    schedule 10.01.2019

arrow_upward
0
arrow_downward

Существующий файл {example.rst} может быть связан со следующим синтаксисом:

:ref:`Optional Link text <example>`

Однако вставьте это в тему или даже в маркер, и поведение может измениться. Итак, вы можете обратиться к окончательному собранному файлу:

`Optional Link text <example.html>`_

Вот отличное руководство

person m4sterbunny    schedule 20.02.2021
comment
Шпаргалка по TYPO3, с которой вы связались, содержит некоторые специфические для TYPO3 вещи, которые используются при рендеринге документов в TYPO3-land. Например, я считаю, что Settings.cfg специфичен. Кроме того, это хороший ресурс. Но я бы дал ссылку на общие документы restructuredText / sphinx, например docs.readthedocs.io/ ru / stable / guides / Если вы хотите перейти по ссылке к другому руководству, поищите intersphinx. - person Sybille Peters; 20.02.2021

arrow_upward
0
arrow_downward

Для ссылки с одной страницы (файла .rst) в вашем проекте на другую страницу (другой файл .rst) используйте следующий встроенный формат:

See :ref: `topLevelHeadingofOtherPage`

Например:

See :ref:`Perform Bulk Actions`.

Вот и все. Я согласен, эту информацию сложно найти в гайде по Sphinx. Это потому, что это так просто, я думаю, люди предполагают, что вы хотите сделать что-то гораздо более сложное.

person Simon Crum    schedule 10.07.2021

arrow_upward
-6
arrow_downward

Для ссылки на другие файлы мне пришлось включить в conf.py. Я взял код из документации Pillow (вилка PIL) здесь.

extensions = ['sphinx.ext.intersphinx']

Думаю, мне на помощь пришло расширение inter-sphinx. Он связан с другими страницами документов.

person Aditya ultra    schedule 04.06.2016
comment
Не могли бы вы также описать, как вы пишете ссылку на другой документ? - person Jindra Helcl; 12.03.2017