Переопределить объявление функции в 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, который выглядит примерно так:

: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.)


python documentation python-sphinx autodoc
person Michael0x2a    schedule 22.08.2012    source источник

Ответы (1)


arrow_upward
16
arrow_downward

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

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

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

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

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

    def myfunc(val=foobar):
    '''myfunc(val=foobar)

    Blah blah blah'''
    pass

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

    В вопросе у вас есть первая строка в строке документации:

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

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

person mzjn    schedule 23.08.2012
comment
Можно ли сделать это для классов (точнее, их конструкторов)? - person detly; 09.12.2012
comment
Это круто, я открыл совершенно новый вопрос об этом < /а>. - person detly; 10.12.2012
comment
Вы можете сделать это еще проще, поместив желаемую сигнатуру функции в файл .rst после autofunction, например .. autofunction:: myfunc(val=foobar), чтобы ваша фактическая строка документации была более удобочитаемой. работает на меня - person Mark Mikofski; 23.09.2015
comment
@MarkMikofski Но тогда функция может быть упорядочена не так, как вы хотите, когда вы используете .. auto*::\n :members: - person Mad Physicist; 29.05.2019