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

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

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

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

Док в вопросе: http://todx.rtfd.io

Ответ 1

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

extensions = ['sphinx.ext.intersphinx']

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

Ответ 2

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

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

.. _my-reference-label:

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

:ref:'my-reference-label'.

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

Ответ 3

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

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

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

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

extensions = ['sphinx.ext.intersphinx']

Ответ 4

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

:doc:'path/to/document'

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

Вам не нужно расширение между сфинксами для этого.