Question

我正在使用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等，参数，退货等都不会在一行上格式化。

这些是否必要？

Answer 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

文档字符串信息字段列表需要py：方法吗？

1 个答案: