如何在 sphinx 中記錄用@dataclass 注釋的可調用類？

Question

我研究了這個話題，但看不到明確的解決方案。 有一個類似的問題

我的問題是我有一個帶有attr.dataclass和typing_extensions.final注釋的類，我不希望它們被記錄下來，但我仍然想從如何調用它的角度來描述這個類。

例如，

@final
@dataclass(frozen=True, slots=True)
class Casting(object):

  _int_converter_function = int
  _float_converter_function = float

  def __call__(self, casting, value_to_cast):
    if casting['type'] == 'integer':
        return self._int_converter_function(value_to_cast)
    return self._float_converter_function(value_to_cast)

這大約相當於這個（這遠非准確）：

class Casting(object):

  def __init__(
    self,
    int_converter_function = int,
    float_converter_function = float,
  ):
    self.int_converter_function = int_converter_function
    self.float_converter_function = float_converter_function

  def converter(self, casting, value):
    self.value = value
    yield
    type = casting['type']
    if type == 'integer':
      yield self.int_converter_function(value)
    else:
      yield self.float_converter_function(value)

最新的很明顯，我可以用文檔字符串記錄每個方法，並在Sphinx做：

.. autoclass:: package.Casting
  :members:
  .. automethod:: __init__(self, int_converter_function, float_converter_function)

如何對注釋做同樣的事情？

更新：

我發現我的問題應該更具體。 我想要

1. 從文檔中完全消除dataclass ，但仍然在文檔中保留該類。 它把課程弄得一團糟，以至於文檔不可讀。

2. 在__init__上創建一個文檔字符串，但也要將其與可調用描述分開。 我留下了評論。

文檔示例：

"""Cast one type of code to another.

Constructor arguments:

    :param int_converter_function: function to convert to int

    :param float_converter_function: function to convert to float

Callable arguments:

:param casting: :term:`casting` object
:type casting: dict

:param value_to_cast: input value

:return: Casted value

Example
    >>> cast = Casting(int)
    >>> cast({'type': 'integer'}, '123')
    123
    >>> cast({'type': 'decimal'}, '123.12')
    Decimal('123.12')

"""

更新 2：

完整的課程如下：

# -*- coding: utf-8 -*-

from attr import dataclass
from typing_extensions import final


@final
@dataclass(frozen=True, slots=True)
class Casting(object):
    """Cast one type of code to another.

    Constructor arguments:

        :param int_converter_function: function to convert to int

        :param float_converter_function: function to convert to float

    Callable arguments:

    :param casting: :term:`casting` object
    :type casting: dict

    :param value_to_cast: input value

    :return: Casted value

    Example
        >>> cast = Casting(int)
        >>> cast({'type': 'integer'}, '123')
        123
        >>> cast({'type': 'decimal'}, '123.12')
        Decimal('123.12')

    """

    _int_converter_function = int
    _float_converter_function = float

    def __call__(self, casting, value_to_cast):
        if casting['type'] == 'integer':
            return self._int_converter_function(value_to_cast)
        return self._float_converter_function(value_to_cast)

我想從文檔中刪除package.casting.dataclass 。

Answer 1

正如@mzjn 在評論中提到的:exclude-members: dataclass如果自動automodule配置正確， :exclude-members: dataclass應該完成這項工作。

我犯了一個難以追蹤的愚蠢錯誤。 如果您在單獨的行中寫入:exclude-members:和<name-of-module> ，則文件中的所有類都將被忽略。

與 make 構造函數和可調用函數相關的另一部分看起來很漂亮，我提取到單獨的SO 問題中。