方法的标准 Sphinx 文档格式是什么？答案

【问题标题】：What is the standard Sphinx documentation format for a method?方法的标准 Sphinx 文档格式是什么？
【发布时间】：2015-12-02 21:44:14
【问题描述】：

我正在尝试使用标准格式记录我的方法，但在搜索中我发现了许多“标准” 方法记录方法。我的方法是：

@staticmethod
def validateMasterAttribute(attribute):
    ...

根据this official Python documentation，我应该这样记录：

@staticmethod
def validateMasterAttribute(attribute):
    """ Validate that the entered master attribute has all the required nodes

    Keyword arguments:
    attribute -- type lxml.etree._Element, it is the xml node for the master attribute

    Return:
    Nothing if the node contains all the required sub nodes. Otherwise, it throws a TagNotFoundException exception
    """
    ...

但是，它是用this question 写的，我应该像这样记录它：

@staticmethod
def validateMasterAttribute(attribute):
    """

    Validate that the entered master attribute has all the required nodes
    :attribute: type lxml.etree._Element, it is the xml node for the master attribute
    return: Nothing if the node contains all the required sub nodes. Otherwise, it throws a TagNotFoundException exception
    """
    ...

我还发现了另一种文档字符串格式，它看起来很旧。 Sphinx 可以解析和生成网页的格式是什么？

【问题讨论】：

有几种“文档方式”，特别是在扩展 Sphinx 时 - 例如 Numpy 和 Google。 PEP 只定义了文档字符串在代码中的布局方式，您需要阅读例如Sphinx 文档，了解它们应该如何具体格式化以进行后处理。
事实上，PEP 在顶部的右边很清楚（强调我的）：“这个 PEP 的目的是标准化文档字符串的高级结构：它们应该做什么包含，以及如何说（不涉及文档字符串中的任何标记语法）。”

标签： python python-sphinx

【解决方案1】：

您可能想咨询Documenting Your Project Using Sphinx。

您也可以使用Napoleon，这是一个支持 google 文档语法的扩展。

选择一个。保持一致。

【讨论】：