Sphinx文档模块属性 [英] Sphinx document module properties

问题描述

我有一个应该有@property的模块，我通过将一个类设置为模块来解决了这个问题.我从以下答案中得到了这个主意:惰性模块变量-可以可以吗?

I have a module that should have a @property, I solved this by setting a class as the module. I got the idea from this answer: Lazy module variables--can it be done?

我希望它是可重复的且易于使用的，所以我为此创建了一个元类.就像魅力一样.

I wanted this to be repeatable and easy to use so I made a metaclass for it. This works like a charm.

问题在于，使用Sphinx生成文档属性时不会记录文档.其他所有内容均按预期记录.我不知道该如何解决，也许这是Sphinx的问题?

The problem is that when using Sphinx to generate documentation properties don't get documented. Everything else is documented as expected. I have no idea how to fix this, maybe this is a problem with 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文档:

And a copy-paste to generate/view Sphinx documentation:

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

最重要的部分是记录类的属性.奖励还可以记录原始模块成员.

The most essential part is to document the class' properties. Bonus points to also document original module members.

编辑:该类应作为其所在的模块进行记录.该类以这种方式使用，因此应以这种方式出现在Sphinx中.

The class should be documented as the module it is in. The class is used this way and should thus appear this way in Sphinx.

所需输出示例:

Module Foo
    TestClass docstring.

    some_property
        Property docstring.

    meth()
        meth doc

我发现了一些可能有助于寻找解决方案的东西.当具有以下内容的常规模块foo时:

EDIT 2: I found something that may aid in finding a solution. When having a regular module foo with the following content:

#: Property of foo
prop = 'test'

Sphinx像这样记录:

Sphinx documents this like:

foo.prop = 'test'
    Property of foo

如果prop是类的属性，则其工作原理相同.我还没有弄清楚为什么在我的特殊情况下它不起作用.

The same works if prop is an attribute of a class. I haven't figured out why it doesn't work in my special case.

推荐答案

这是我的理解.

理论是:以这种(有点怪异的方式)使 amutant 您的类像一个模块一样工作，使狮身人面像认为他不需要(解析)模块的属性(因为它是一个类级范例).因此，对于狮身人面像，TestClass是一个模块.

The theory is: making a mutant your class act like a module this (a bit hacky) way makes sphinx think that he doesn't need (to parse) properties from modules (because it's a class-level paradigm). So, for sphinx, TestClass is a module.

首先，要确保罪魁祸首是使类像模块一样起作用的代码-让我们将其删除:

First of all, to make sure that the culprit is the code for making a class act like a module - let's remove it:

class ClassAsModule(type):
    pass

我们将在文档中看到

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.

如您所见，狮身人面像读取属性没有任何问题.这里没什么特别的.

As you see, sphinx read the property without any problems. Nothing special here.

针对您的问题的可能解决方案是避免使用@property装饰器，并将其替换为调用property类构造器.例如:

Possible solution for your problem is to avoid using @property decorator and replace it with calling property class constructor. E.g.:

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

对于此代码，狮身人面像生成:

For this code sphinx generates:

package Package
    script Module
        TestClass docstring.

            package.script.get_some_property(self)
                Property docstring.

            package.script.meth(self)
                meth doc

也许答案是胡说八道，但我希望它能为您指明正确的方向.

May be the answer is a piece of nonsense, but I hope it'll point you to the right direction.

这篇关于Sphinx文档模块属性的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！