Python Sphinx, ссылающийся на длинные имена

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

вот пример:

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

    '''

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

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

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

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

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

:class:`module1.module2.ReallyLongClassName`

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

любая помощь будет высоко оценили.


изменить 04/05/2012:

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

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

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

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

    '''

красиво, и некрасиво. Если бы вы ставить пробелы перед "ReallyLongExampleClassName", чтобы выравнить его до уровня линии выше его выходные данные будут содержать пробелы и, таким образом, Сфинкс пытался что-то ссылка "модуль1.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`

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

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

8
documentation python python-sphinx restructuredtext

4 ответов

согласно документации Сфинкса(http://sphinx.pocoo.org/domains.html?highlight=current#cross-referencing-python-objects) Вы можете использовать точку перед целевым классом:

:class:`.ReallyLongExampleClassName`

или 

:class:`.module5.ReallyLongExampleClassName`

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

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

13

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

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

2

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

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

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

import scipy.\
stats
1

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

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

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

    '''

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

rst_epilog

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

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

New в версии 0.6.

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

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

    '''
1