Объявление функции переопределения в autodoc для sphinx

У меня есть модуль, который выглядит примерно так:

#!/usr/bin/env python #: Documentation here. #: blah blah blah foobar = r'Some really long regex here.' def myfunc(val=foobar): '''Blah blah blah''' pass 

… и у меня есть .rst файл, который .rst примерно так:

 :mod:`my_module` Module ----------------------- ..automodule:: my_module :members: :private-members: :show-inheritance: 

Когда я создаю документацию, я получаю html-файл с фрагментом, который выглядит следующим образом:

mymodule.foobar. foobar = 'Некоторое абсурдно длинное и уродливое регулярное выражение здесь'

Дополнительная документация здесь

MyModule. myfunc ( val = 'Некоторое абсурдно длинное и уродливое регулярное выражение здесь )

бла бла бла

Основываясь на этой записи stackoverflow , я подумал, что могу изменить ее, изменив свой модуль на:

 #!/usr/bin/env python #: .. data:: my_module.foobar #: Extra documentation here foobar = 'Some really long regex here.' def myfunc(val=foobar): '''.. function:: my_module.myfunc(val=foobar) Blah blah blah''' pass 

… но это не сделало этого трюка и просто приложило подпись, которую я хотел под уродливым, как часть тела. Кто-нибудь знает, как я могу правильно переопределить это?

(Я использую Sphinx v1.1.3, кстати.)

One Solution collect form web for “Объявление функции переопределения в autodoc для sphinx”

У вас есть переменная уровня модуля, которая используется в качестве значения по умолчанию аргумента ключевого слова в функции. Sphinx отображает значение (вместо имени) этой переменной в сигнатуре функции. Эта проблема обсуждается в другом вопросе , и ОП также отправил в GitHub вопросный билет .

Однако вы можете обойти это двумя способами:

  1. Переопределите подпись в файле .rst с помощью autofunction , как объясняется в ответе на связанный вопрос.

  2. Если первая строка docstring выглядит как подпись, и если для параметра конфигурации autodoc_docstring_signature установлено значение True (которое по умолчанию), Sphinx будет использовать эту строку в качестве подписи.

    Итак, если у вас есть docstring, который выглядит следующим образом,

     def myfunc(val=foobar): '''myfunc(val=foobar) Blah blah blah''' pass 

    он должен работать так, как вы этого хотите.

    В этом вопросе у вас есть первая строка в docstring:

     .. function:: my_module.myfunc(val=foobar) 

    Это не работает, потому что это не похоже на правильную подпись.

Python - лучший язык программирования в мире.