Ссылка на длинные имена с помощью Python Sphinx

Я работаю над документацией для своего модуля Python (используя Sphinx и reST) и обнаружил, что при перекрестных ссылках на другие объекты Python (модули, классы, функции и т. д.) полное имя объекта оказывается невероятно длинным. Часто он длиннее 80 символов, чего хотелось бы избежать любой ценой.

Вот пример:

def exampleFunction():
    '''Here is an example docstring referencing another
    :class:`module1.module2.module3.module4.module5.ReallyLongExampleClassName`

    '''

Проблема в том, что при создании документации для класса ReallyLongExampleClassName я создал ее для полного имени пути module1.module2.module3.module4.module5.ReallyLongExampleClassaName.

Мне интересно, есть ли способ решить это? Я пробовал следующие методы, но безуспешно:

1) Добавление разрыва строки в середине имени модуля. Пример:

:class:`module1.module2.module3.module4.
module5.ReallyLongExampleClassName`

2) Ссылка на имя класса другим (но все же импортируемым в Python) способом. Пример:

:class:`module1.module2.ReallyLongClassName`

Я считаю, что, поскольку документация для ReallyLongClassName привязана к полным путям, Sphinx не может соотнести сокращенную версию с полной версией.


Редактировать 05.04.2012:

В соответствии с ответом/предложением j13r (см. ниже) я попробовал следующее:

:class:`module1.module2.module3.module4.module5\
ReallyLongExampleClassName`

И это сработало успешно. Единственное предостережение, чтобы заставить это работать, заключается в том, что перед второй строкой не должно быть пробелов (что довольно неприятно при использовании этого в строке документации). Таким образом, чтобы заставить мой первоначальный пример работать, он будет выглядеть так:

def exampleFunction():
    '''Here is an example docstring referencing another
    :class:`module1.module2.module3.module4.module5.\
ReallyLongExampleClassName`

    '''

Красиво и некрасиво. Если бы вы поставили пробелы перед ReallyLongExampleClassName, чтобы сделать отступ на том же уровне, что и строка над ней, вывод будет включать пробелы, и, таким образом, Sphinx попытается сослаться на что-то вроде module1.module2.module3.module4.module5.ReallyLongExampleClassName.

Я также должен отметить, что я пробовал два других варианта этого, которые НЕ работали:

    # Note: Trying to put a space before the '\'
    :class:`module1.module2.module3.module4.module5. \
ReallyLongExampleClassName`

    # Note: Trying to leave out the '\'
    :class:`module1.module2.module3.module4.module5.
ReallyLongExampleClassName`

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

Спасибо j13r за ответ!


python python-sphinx cross-reference restructuredtext
person furtypajohn    schedule 05.04.2012    source источник

Ответы (4)


arrow_upward
19
arrow_downward

Согласно документации sphinx (https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects) вы можете поставить точку перед целевым классом:

:class:`.ReallyLongExampleClassName`

or 

:class:`.module5.ReallyLongExampleClassName`

и пусть sphinx ищет класс:

... если имя начинается с точки и точное совпадение не найдено, цель берется как суффикс, и ищутся все имена объектов с этим суффиксом. Например, :py:meth:.TarFile.close ссылается на функцию tarfile.TarFile.close(), даже если текущий модуль не является tarfile. Поскольку это может быть неоднозначным, если существует более одного возможного совпадения, вы получите предупреждение от Sphinx.

person bmu    schedule 08.04.2012

arrow_upward
3
arrow_downward

Вы можете использовать ~ в качестве префикса, он делает именно то, что вы хотите.

http://sphinx-doc.org/markup/inline.html#xref-syntax

person Bertrand Mathieu    schedule 10.07.2015

arrow_upward
2
arrow_downward

Другая стратегия заключается в использовании reST замен. Это позволит вам сэкономить больше места в тексте, вызывая перекрестную ссылку :class: позже:

def exampleFunction():
    '''Here is an example docstring referencing another
    |ReallyLongExampleClassName|

    .. |ReallyLongExampleClassName| replace:: 
                                    :class:`.ReallyLongExampleClassName`

    '''

Если вы ссылаетесь на один и тот же класс во многих своих файлах, вы можете вместо этого поместить замену в свой файл conf.py Sphinx, используя rst_epilog. Из документации Сфинкса:

первый_эпилог

Строка reStructuredText, которая будет включена в конец каждого прочитанного исходного файла. Это правильное место для добавления замен, которые должны быть доступны в каждом файле. Пример:

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

Новое в версии 0.6.

Тогда ваша docstring будет просто:

def exampleFunction():
    '''Here is an example docstring referencing another
    |ReallyLongExampleClassName|

    '''
person Leila Hadj-Chikh    schedule 03.02.2016
comment
Потрясающий! Я использовал (например,) :ref:`<topic-name>` для размещения ссылок в заголовках некоторых столбцов таблицы, что делало всю исходную таблицу слишком широкой. Изменение заголовков только на |topic| упрощает редактирование намного. - person medmunds; 15.03.2016

arrow_upward
1
arrow_downward

Дикий удар в темноте. Возможно, это работает:

:class:`module1.module2.module3.module4.\
module5.ReallyLongExampleClassName`

Это было бы действительно Python

import scipy.\
stats
person j13r    schedule 05.04.2012