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）。 但是，源代碼仍然具有可讀性。