文档字符串信息字段列表是否需要 py:method？答案

【问题标题】：Is py:method needed for docstring info field lists?文档字符串信息字段列表是否需要 py:method？
【发布时间】：2014-08-13 20:12:28
【问题描述】：

我正在使用 sphinx-apidoc 从 Python 文档字符串中收集文档。

为了获得格式化的Parameters、Returns、Raises和其他sphinx文档部分，看来我需要把.. py:method::或其他类似的域表示，如这个琐碎的类所示：

class Message(object):
    """
    .. py:class::
       Base class representing a message.
    """

    DEFAULT_PRIORITY = 5

    def __init__(self):
        """
        .. py:method::
           Constructor.
        """
        self.priority = Message.DEFAULT_PRIORITY

    def set_priority(self, priority):
        """
        .. py:method::
           Set the message priority.

        :param int priority: The new message priority.
        :return: The old message priority.
        :rtype: int
        :raise TypeError: The given priority is not an int.
        """
        if not isinstance(priority, int):
            raise TypeError
        old_priority = priority
        self.priority = priority
        return old_priority

如果没有.. py:method 等，参数、返回等将在一行中未格式化。

这些有必要吗？

【问题讨论】：

标签： python-sphinx

【解决方案1】：

不，不需要.. py:method 部分。所需要的是将描述与:param 和其他块分开的换行符，如下所示：

class Message(object):
    """
    Base class representing a message.
    """

    DEFAULT_PRIORITY = 5

    def __init__(self):
        """
        Constructor.
        """
        self.priority = Message.DEFAULT_PRIORITY

    def set_priority(self, priority):
        """
        Set the message priority.

        :param int priority: The new message priority.
        :return: The old message priority.
        :rtype: int
        :raise TypeError: The given priority is not an int.
        """
        if not isinstance(priority, int):
            raise TypeError
        old_priority = priority
        self.priority = priority
        return old_priority

【讨论】：