Sphinx文档模块属性

Question

我有一个应该有@property的模块，我通过将类设置为模块来解决这个问题。 我从这个答案中得到了一个想法： 懒惰的模块变量 - 可以做到吗？

我希望这个可重复且易于使用，所以我为它制作了一个元类。 这就像一个魅力。

问题是，当使用Sphinx生成文档属性时，请不要记录。 其他所有内容都按预期记录。 我不知道如何解决这个问题，也许这是Sphinx的一个问题？

模块：

import sys
import types

class ClassAsModule(type):
    def __new__(cls, name, bases, attrs):
        # Make sure the name of the class is the module name.
        name = attrs.pop('__module__')
        # Create a class.
        cls = type.__new__(cls, name, bases, attrs)
        # Instantiate the class and register it.
        sys.modules[name] = cls = cls(name)
        # Update the dict so dir works properly
        cls.__dict__.update(attrs)

class TestClass(types.ModuleType):
    """TestClass docstring."""
    __metaclass__ = ClassAsModule
    @property
    def some_property(self):
        """Property docstring."""
        pass
    def meth():
        """meth doc"""
        pass

以及用于生成/查看Sphinx文档的复制粘贴：

sphinx-apidoc . -o doc --full
sphinx-build doc html
xdg-open html/module.html

最重要的部分是记录班级的属性。 奖励指向还记录原始模块成员。

编辑：该类应记录为它所在的模块。该类以这种方式使用，因此应该以这种方式出现在Sphinx中。

期望输出的示例：

Module Foo
    TestClass docstring.

    some_property
        Property docstring.

    meth()
        meth doc

编辑2：我找到了一些可能有助于找到解决方案的东西。 当具有以下内容的常规模块foo时：

#: Property of foo
prop = 'test'

Sphinx记录如下：

foo.prop = 'test'
    Property of foo

如果prop是类的属性，则同样有效。 我还没弄清楚为什么它在我的特殊情况下不起作用。

Answer 1

这是我的理解。

理论是：使 一个突变体 你的类就像一个模块这个（有点hacky）方式使得sphinx认为他不需要（解析）模块中的属性（因为它是一个类级别的范例）。 因此，对于sphinx， TestClass是一个模块。

首先，要确保罪魁祸首是使类像模块一样的代码 - 让我们删除它：

class ClassAsModule(type):
    pass

我们将在docs中看到：

package Package
    script Module

    class package.script.ClassAsModule
        Bases: type

    class package.script.TestClass
        Bases: module

        TestClass docstring.

        meth()
            meth doc

        some_property
            Property docstring.

如您所见，sphinx读取属性没有任何问题。 这里没什么特别的。

---

您的问题的可能解决方案是避免使用@property装饰器并将其替换为调用property类构造函数。 例如：

import sys
import types

class ClassAsModule(type):
    def __new__(cls, name, bases, attrs):
        # Make sure the name of the class is the module name.
        name = attrs.pop('__module__')
        # Create a class.
        cls = type.__new__(cls, name, bases, attrs)
        # Instantiate the class and register it.
        sys.modules[name] = cls = cls(name)
        # Update the dict so dir works properly
        cls.__dict__.update(attrs)


class TestClass(types.ModuleType):
    """TestClass docstring."""
    __metaclass__ = ClassAsModule

    def get_some_property(self):
        """Property docstring."""
        pass

    some_property = property(get_some_property)

    def meth(self):
        """meth doc"""
        pass

对于此代码，sphinx生成：

package Package
    script Module
        TestClass docstring.

            package.script.get_some_property(self)
                Property docstring.

            package.script.meth(self)
                meth doc

答案可能是一个废话，但我希望它会指向正确的方向。

Answer 2

我发现最好的方法是保持文件内容和编写常规模块一样，然后在sys.modules替换胚胎模块：

"""Module docstring.  """

import sys
import types

def _some_property(self):
    pass
some_property = property(_some_property)
"""Property docstring."""

def meth():
    """meth doc"""
    pass

def _make_class_module(name):
    mod = sys.modules[name]
    cls = type('ClassModule', (types.ModuleType,), mod.__dict__)
    clsmod = cls(name)
    clsmod.__dict__.update(mod.__dict__)
    clsmod.__wrapped__ = mod
    sys.modules[name] = clsmod
_make_class_module(__name__)

文字文件：

mymod Module
************

Module docstring.

mymod.meth()

   meth doc

mymod.some_property = None

   Property docstring.

对于我正在使用的Sphinx版本（v1.1.3），看起来你必须显式地应用属性构造函数（你不能将它用作装饰器），并且docstring必须放在顶部的文件中level，在构造函数调用之后的行上创建属性（它不能作为属性getter中的docstring）。 但是，源代码仍然具有可读性。