Как связать локальные справочные документы Python с помощью Sphinx - PullRequest
Новая
       5

Как связать локальные справочные документы Python с помощью Sphinx

0 голосов
/ 26 мая 2018

Как я могу получить в своем Sphinx RST-файле ссылку на страницу справки Python "contents.html"?

Подробнее

У меня есть RSTсправочный документ ( index.rst ) в автономном режиме.Я скачал и успешно собрал документацию по Python с помощью команды make.bat html.Затем я скопировал эту документацию в C: \ Temp \ PyDoc.

Затем я обновил свой файл conf.py, добавив в него следующее сопоставление Intersphinx: 

intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}

Затем внутри моего index.rst файл, у меня есть что-то вроде: 

Contents:

.. toctree::
   :maxdepth: 1

   :ref:`Python <python:contents>`

Ссылка Python удалена из итоговой документации с предупреждением:

ВНИМАНИЕ: toctree содержит ссылку на несуществующий документ ': ref: `Python`'

Я проверил, что вывод содержит текст:

загрузка инвентаризации межфинкса из C: /Temp/PyDoc/objects.inv ...

Я также проверил, что тег "содержимое" существует в документации Python, выполнив: 

python -m sphinx.ext.intersphinx "C:/Temp/PyDoc/objects.inv" | findstr contents

, который генерирует вывод, включающий строку:

Содержание Python Документация содержание: contents.html

Кто-нибудь знает, как ссылаться на эту внешнюю документацию из моего файла RST?

1 Ответ

0 голосов
/ 26 мая 2018

В конфигурации для intersphinx значение ключа dict представляет собой кортеж , который состоит из значений через запятую, а не через двоеточие. 

intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}

РЕДАКТИРОВАТЬ

toctree записи должны иметь правильную цель, которая может быть файлом относительно текущего файла или абсолютной, начиная с корня документации, гдеваш conf.py проживает.Также целью может быть URL.Я подозреваю, что созданный вами HTML не является ни одним из вышеперечисленных, поэтому вам нужно переместить его туда, где Sphinx сможет его найти.

Синтаксис должен быть для документации, а не для объекта Python, поскольку страницаоглавление.Я не пробовал этот пример, потому что у меня нет загруженных и собранных документов Python, поэтому я сомневаюсь, что он будет работать. 

.. toctree::
    :maxdepth: 1

    :doc:`Python <python:contents>`

Или вы можете просто использовать URL (или аналогичную относительную или абсолютную цель),Это работает для меня с полным URL. 

.. toctree::
    :maxdepth: 1

    Python <https://docs.python.org/3/contents.html>

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

...