Определение целей для межсинхронных ссылок на numpy, scipy и matplotlib

Следуя документации по настройке ссылок документации Sphinx между пакетами, я добавил

intersphinx_mapping = {'python': ('http://docs.python.org/2', None),
                       'numpy': ('http://docs.scipy.org/doc/numpy/', None),
                       'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
                       'matplotlib': ('http://matplotlib.sourceforge.net/', None)}

для моего conf.py, но, похоже, не может получить ссылки на какой-либо проект, отличный от самого Python. Например

:term:`svg graphics <matplotlib:svg>`

просто приводит меня на страницу индекса, не добавляя якорь #term-svg, и я даже не могу найти глоссарий для scipy или выяснить, как определить, какие :ref: или :term: поддерживаются пакет.

Где я могу найти инструкции о том, как указывать цели для :ref: и :term: в numpy, scipy и matplotlib?

В этом отношении, как я могу связать себя с самим Сфинксом? Добавление

intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', None)

:ref:`Intersphinx <intersphinx>`

не работает.

Ответ 1

Где я могу найти инструкции о том, как указать цели для :ref: и :term: в numpy, scipy и matplotlib?

У меня есть Gist с горсткой отображений intersphinx, которая теперь включает в себя все numpy, scipy и matplotlib. Вы можете использовать эти записи непосредственно в intersphinx_mapping в своем conf.py. Если у кого есть предложения по добавлению новых записей в этот список, пожалуйста, не стесняйтесь отправлять запросы в комментарии Gist.

Для всех этих пакетов, за ответ fgoudra Я настоятельно рекомендую использовать sphobjinv для декодирования и проверки синтаксиса файла objects.inv для каждой библиотеки. (Полное раскрытие: я являюсь автором sphobjinv.) Каждая строка (декодированная) objects.inv предоставляет вам всю информацию, необходимую для создания рабочей ссылки intersphinx; см. документацию sphobjinv здесь.

numpy сложно. Иногда вам требуется полное имя, например:

:func:`numpy.cross`

В других случаях (например, для функций C) вы можете просто ссылаться на базовое имя функции, но вы должны явно указать домен, например:

:c:func:`PyArray_InnerProduct`

Однако иногда вам может потребоваться ссылка на пользовательский домен np, например:

:np:func:`numpy.ma.append`

На самом деле нет способа узнать, что такое правильный синтаксис, не посоветовавшись с objects.inv.

scipy примерно такой же непостижимой, как numpy.. Все это осложняется введением многочисленных пользовательских доменов для различных подпакетов scipy, например:

:scipy-optimize:func:`scipy.integrate.newton_cotes`

Для matplotlib, вам всегда нужно указать (довольно многословное) полностью заданное имя объекта в ссылке, например:

:meth:`matplotlib.axes.Axes.plot`

Все объекты кода matplotlib, похоже, находятся в домене py по умолчанию, что несколько упрощает.

Для любого из них, если у вас возникли проблемы с получением ссылки для правильной сборки, первое, на что я вернусь, - это использовать родовую роль :obj:, например:

:obj:`matplotlib.axes.Axes.plot`

Это построит ссылку intersphinx, независимо от роли, в которой был определен конкретный объект, хотя, я думаю, вам все равно нужно правильно указать любой соответствующий домен, отличный от стандартного. Если ссылка не работает должным образом с ролью :obj:, то там где-то есть ошибка в имени объекта или в домене. Проверьте наличие опечаток в обоих местах.

Ответ 2

Можно вручную указать, какой инвентарь посмотреть. Например, если intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', None) не работает, вы всегда можете загрузить инвентарь и вручную добавить его к сопоставлению (например, загрузить из http://sphinx-doc.org/objects.inv, сохранить двоичный файл в ваши документы и добавьте путь к нему в сопоставлении, это даст что-то вроде:

intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', ('objects.inv', ), )

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

Это может быть не решение вашей проблемы, но может помочь отладить некоторые вещи.