Как я могу предоставить документацию Sphinx для именованного кортежа (с помощью autodoc)?

Я пытаюсь задокументировать проект Python с помощью Sphinx, но у меня возникают проблемы с объединением расширения autodoc с созданным namedtuple классом.

В одном документе gammatone.rst у меня есть:

:mod:`gammatone` -- gammatone filterbank toolkit
================================================

.. automodule:: gammatone
   :members:
.. automodule:: gammatone.coeffs
   :members:

В моем gammatone/coeffs.py есть:

from collections import namedtuple

ERBFilterCoeffs = namedtuple(
    'ERBFilterCoeffs', # Most parameters omitted
    [
        'A0',
        'gain',
    ])

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

Я пробовал поставить что-то вроде этого прямо перед классом:

"""
.. class:: ERBFilterCoeffs(A0, gain)
:param A0: A0 coefficient
:param gain: Gain coefficient

Magic coefficients.
"""

... но это не отображается в сгенерированных документах. Помещение его после класса приводит к тому, что он будет вложен в документацию общего класса, а не заменяет его.

Как мне просто сказать Sphinx (и расширению autodoc) использовать мою документацию для класса ERBFilterCoeffs вместо документации, созданной namedtuple?


python python-sphinx autodoc
person detly    schedule 09.12.2012    source источник

Ответы (3)


arrow_upward
7
arrow_downward

Как насчет того, чтобы после определения ERBFilterCoeffs с помощью namedtuple попробовать присвоить эту строку документа ERBFilterCoeffs.__doc__?

РЕДАКТИРОВАТЬ: Хорошо, а как насчет этого:

class ERBFilterCoeffs(namedtuple('ERBFilterCoeffs','a b c')):
    """
    this is the doc string for ERBFilterCoeffs
    """
person PaulMcG    schedule 09.12.2012
comment
Я получаю: WARNING: autodoc can't import/find module 'gammatone.erb', it reported error: "attribute '__doc__' of 'type' objects is not writable", please check your spelling and sys.path - так что, по-видимому, я не могу перезаписать строку документации сгенерированного namedtuple типа: / - person detly; 09.12.2012
comment
В качестве побочного эффекта это будет отображаться как base, что немного парадоксально ... В остальном документация оказывается в порядке :) - person exhuma; 12.09.2014

arrow_upward
13
arrow_downward

На самом деле вам вообще не нужно расширять именованный кортеж. Вы можете поместить строку документации после именованного кортежа. Это действительно работает и для констант и атрибутов.

ERBFilterCoeffs = namedtuple('ERBFilterCoeffs', ['A0', 'gain', ])
""" Magic coefficients.

.. py:attribute:: A0

    The A0 attribute is something

.. py:attribute:: gain

    The gain attribute is blah blah

"""
person dnephin    schedule 13.12.2013
comment
В моем случае размещение его после класса приводит к тому, что он будет вложен в документацию общего класса, а не заменяет его. - person detly; 14.12.2013
comment
Это не сработает. Здесь вы создаете именованный набор, присвоенный переменной ERBFilterCoeffs, а затем определяете многострочную строку в вакууме. - person Alex Conrad; 16.04.2015
comment
@aconrad вот как sphinx документирует константы, это работает для sphinx, но, возможно, не для ERBFilterCoeffs.__doc__ - person dnephin; 17.04.2015
comment
Вы можете не указывать :members: в директиве autoclass. Единственная проблема заключается в том, что в этом случае нельзя полагаться на :members: - automodule, и вам придется перечислить содержимое модуля вручную. - person Mad Physicist; 29.12.2017
comment
Я пробовал этот метод, и он почти работает для меня, но он добавляет к именам атрибутов имя модуля. Я не могу использовать глобальные настройки add_module_names = False, потому что хочу их где-нибудь еще. И я не могу аннотировать some_name в :py:attribute:: some_name тильдой ~ или подобным: аннотации просто включены буквально. Это можно обойти? - person Dan Halbert; 28.01.2020

arrow_upward
-1
arrow_downward

В общем, я предпочитаю иметь более тонкий контроль над тем, что генерируется, чем добавление директивы :members: в automodule. Таким образом, я бы рекомендовал документировать ERBFilterCoeffs явно с помощью .. autoclass:: ERBFilterCoeffs. Я бы не стал добавлять сюда директиву :members:, поскольку она будет включать очень общие документы по умолчанию, которые namedtuple создает для каждого поля. Вместо этого я бы использовал .. py:attribute:: ... элементы в вашей строке документации, которые вы можете поместить перед определением класса, используя специальные комментарии #::

#: Magic coefficients.
#:
#: .. py:attirbute:: A0
#:
#:    A0 coefficient
#:
#: .. py:attribute:: gain
#:
#:    Gain coefficient
ERBFilterCoeffs = namedtuple(
    'ERBFilterCoeffs', [# Most parameters omitted
        'A0',
        'gain',
    ]
)
person Mad Physicist    schedule 22.12.2017