python - 使用类型注释记录类属性

Question

我想从文档字符串自动生成文档到我的代码。我有一些用于存储一些数据的基本类：

class DataHolder:
    """
    Class to hold some data

    Attributes:
        batch: Run without GUI
        debug (bool): Show debug messages
    """
    batch: bool = False
    debug: bool = False
    name: str = 'default'
    """Object name"""
    version: int = 0
    """int: Object version"""

我的rst文件：

DataHolder
==========

.. autoclass:: data_holder.DataHolder
   :members:

我以不同的方式记录了每个属性以显示差异，这是输出：

似乎 Sphinx 无法将该Attributes部分与真实属性联系起来，这就是它无法显示其默认值的原因。

我想要实现的最终输出是version与定义为 for 的文档字符串的字段的结果batch。我想用默认值和类型显示属性名称，但取自类型注释。在这种情况下，Sphinx 似乎忽略了类型注释。

我的狮身人面像扩展：

extensions = [
    'sphinx.ext.viewcode',
    'sphinx.ext.autodoc',
    'sphinxcontrib.napoleon',
]

我该怎么做才能实现这种行为？对于这种用例，我找不到任何好的例子。

Answer 1

我不认为你可以在你的文档字符串中放置一个属性部分来获得你想要的结果。

我尝试给每个属性一个文档注释并指定类型和所需的注释。

class DataHolder:
"""
Class to hold some data

Each attribute needs its own doc comment with its type
"""

#: bool: Run without Gui
batch = False

#: bool: Show debug messages
debug = False

#: str: Object Name
name = 'default'

#: int: Object Version
version = 0

这给出了以下输出和每个输出的漂亮类型描述。

看看这里：

Answer 2

class DataHolder:
    """
    Class to hold some data

    Attributes:
        batch: Run without GUI
        debug (bool): Show debug messages
        name: Object name
        version: Object version
    """
    batch: bool = False
    debug: bool = False
    name: str = 'default'
    version: int = 0
    # INLINE COMMENT for ONE line
    """
    DocString as inline-comment I havent seen that yet.
    """

Answer 3

There is an inbuilt library for document generation from doc_strings.

https://docs.python.org/2/library/pydoc.html

All you need is to execute

$ pydoc <modulename>

It gives a beautiful documentation listing the doc_strings, defines the parameters and the return values. Just give a try.