Как мне задокументировать конструктор для класса с использованием классов данных Python?

Строки документов в стиле наполеона, как они описаны в документах по сфинксу (см. класс ExampleError, чтобы узнать об этом) явно коснитесь вашего случая:

Метод __init__ может быть задокументирован либо в строке документации уровня класса, либо как строка документации в самом методе __init__.

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

Это означает, что вы можете просто вставить информацию о конструкторе в тело строки документации класса.

В случае, если вы создаете документы из своих строк документации, вот детали, которые могут быть достигнуты:

1) Самый минимум:

@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.
    """
    var_int: int
    var_str: str

2) Дополнительное описание параметра конструктора:

@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.

    Args:
        var_int (int): An integer.
        var_str (str): A string.

    """
    var_int: int
    var_str: str

3) Описание дополнительного атрибута:

@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.

    Attributes:
        var_int (int): An integer.
        var_str (str): A string.

    """
    var_int: int
    var_str: str

Описания параметров и атрибутов, конечно, также можно комбинировать, но поскольку классы данных должны быть прямыми сопоставлениями, я не вижу причин для этого.

На мой взгляд, 1) подойдет для небольших или простых классов данных - он уже включает сигнатуру конструктора с соответствующими типами, чего достаточно для класса данных. Если вы хотите подробнее рассказать о каждом атрибуте, лучше всего подойдет 3).

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

@dataclass
class InventoryItem:
    '''Class for keeping track of an item in inventory.'''
    name: str
    unit_price: float
    quantity_on_hand: int = 0

    def total_cost(self) -> float:
        return self.unit_price * self.quantity_on_hand

Если вы не ожидаете, что читатели вашего кода будут знать, как работают классы данных, вы можете пересмотреть их использование или добавить объяснение или ссылку на документы во встроенном комментарии после декоратора @dataclass. Если вам действительно нужна строка документации для класса данных, я бы рекомендовал поместить строку документации конструктора в строку документации класса. В приведенном выше примере:

'''Class for keeping track of an item in inventory.

Constructor arguments:
:param name: name of the item
:param unit_price: price in USD per unit of the item
:param quantity_on_hand: number of units currently available
'''

Думаю, самый простой способ:

@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.

    """
    var_int: int  #: An integer.

    #: A string.
    #: (Able to have multiple lines.)
    var_str: str

    var_float: float
    """A float. (Able to have multiple lines.)"""

Не знаю, почему результаты, обработанные @Arne, выглядят так. В моем случае атрибуты в классе данных всегда будут отображаться независимо от строки документации. Это:

1) Самый минимум:

2) Дополнительное описание параметра конструктора:

3) Описание дополнительного атрибута:

Вероятно, потому что я что-то неправильно установил в своем conf.py (Sphinx v3.4.3, Python 3.7):

extensions = [
    "sphinx.ext.napoleon",
    "sphinx.ext.autodoc",
    "sphinx_autodoc_typehints",
    "sphinx.ext.viewcode",
    "sphinx.ext.autosectionlabel",
]

# Napoleon settings
napoleon_google_docstring = True
napoleon_include_init_with_doc = True