Можно ли переопределить autodoc Sphinx для определенных функций?

Я использую Sphinx autodoc plugin, чтобы автоматически документировать набор модулей. У меня есть функция, которая принимает *args, и я хотел бы переопределить документацию, чтобы показать немного более приятный стиль funcname(arg1[, arg2[, ...]]), который используют документы stdlib Python.

Можно ли переопределить вывод autodoc для определенной функции?

Ответы

Ответ 1

Можно переопределить подпись с помощью autofunction:

.. automodule:: yourmodule
   :members:
   :exclude-members: funcname

.. autofunction:: funcname(arg1[, arg2[, ...]])

Однако функция с переопределенной сигнатурой не сортируется с другими функциями, втянутыми с помощью automodule. Использование явных директив autofunction для каждой функции работает вокруг этого:

.. autofunction:: firstfunc

.. autofunction:: funcname(arg1[, arg2[, ...]])

.. autofunction:: thirdfunc

Добавление

Вы также можете добавить к docstring:

.. autofunction:: funcname(arg1[, arg2[, ...]])

   Extra documentation here.

Чтобы переопределить подпись и docstring, используйте function вместо autofunction.

Дополнение 2

Подпись также может быть переопределена путем наличия подписи в качестве первой строки функции docstring. Подробнее см. этот ответ.