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 за ответ!

9
задан furtypajohn 6 April 2012 в 02:26
поделиться