如何为 sphinx 文档保留装饰类的文档字符串？

Posted 2023-02-23

【中文标题】如何为 sphinx 文档保留装饰类的文档字符串？

【英文标题】：How to preserve a docstring of a decorated class for sphinx documentation?

【发布时间】：2019-09-02 11:20:42

【问题描述】：

我有一个装饰器，它具有包装类的嵌套定义。 Wrapper 将其包装的原始类作为属性维护。 玩具示例如下所示：

def decorator(cls):
    class Wrapper(object):
        original = cls

        def __init__(self):
            self.__doc__ = self.original.__doc__
            self.__name__ = self.original.__name__

        def do_something_with_cls(cls):
            pass

    return Wrapper

现在我想在另一个模块中用这个装饰器装饰Foo 类，并在装饰之前为Foo 类生成sphinx 文档。它看起来像这样：

from .bar import decorator


@decorator
class Foo(object):
    """The docstring I want to preserve."""
    def __init__(self):
        pass

我试图通过使用autoclass 功能来实现这一点，但没有成功。我想做的是创建一个类实例并获取它的文档字符串：

.. autoclass:: package.baz.Foo()
   :members:

但它在 package.baz.Foo 类的 html 文档中返回了这个：alias of package.bar.decorator.<locals>.Wrapper

我想在记录baz 模块时实现这一点，我能够在装饰之前生成 Foo 类的文档。有可能吗？

编辑：

This 看起来像一个类似的问题，但在这里我想要实现的是将 Sphinx 将看到的文档字符串传递给 Wrapper 实例并根据原始 Foo 文档字符串生成文档，否则我将能够打电话给Wrapper.original 并对此进行记录，但以下没有解决：

.. autoclass package.baz.Foo.original
   :members:

【问题讨论】：

使用wraps

Python functools.wraps equivalent for classes的可能重复

两种解决方案都行不通，因为：1. wraps 与作为参数传递的类不兼容 2. 我在这里用定义 Wrapper 类的函数来装饰整个类。在附加的问题中有装饰函数的类。或者我错过了什么？

【参考方案1】：

如果@wraps 不起作用，您可以手动更新__doc__。

执行以下操作：

def decorator(cls):
    class Wrapper(object):
        original = cls

        def __init__(self):
            self.__doc__ = self.original.__doc__
            self.__name__ = self.original.__name__

        def do_something_with_cls(cls):
            pass

    Wrapper.__doc__ = cls.__doc__
    return Wrapper


@decorator
class Foo(object):
    """The docstring I want to preserve."""
    def __init__(self):
        pass


print(Foo.__doc__)

'我要保留的文档字符串。'

【讨论】：

你是我的英雄！我不知道为什么我没有弄清楚我需要在类定义之外指定这个并且做了同样的事情，但是在 init 阶段......非常感谢，完美！