PyCharm 的文档字符串模板有什么用？我如何有效地使用它？

Question

PyCharm、Python IDE 在我开始输入文档字符串时生成一个文档字符串模板。这是为简单函数生成的模板。

def add_them(x, y):
    """

    :param x: 
    :param y: 
    :return:
    """
    z = x + y
    return z

我没有发现它与 Python 的官方文档字符串 conventions.

有任何相似之处

此模板是否可用于 readthedocs 等任何文档生成器？

人们如何有效地使用？

填写模板的正确方法是什么？

谢谢。

Answer 1

我们将它与 sphinx-apidoc 一起使用来生成我们的 HTML 和 PDF 文档。

这是我如何使用文档字符串的示例：

def add_pdr(process, userid, log):
    """ Create and perform the target account operation PDR

    If the function/method is complex, I'd put a short one-line
    summary in the first line above, and a more detailed explanation
    here.

    :param dict process: dict of process details
    :param str userid: userid to perform actions on
    :param obj log: log object to perform logging to

    :raises KeyError: if the userid doesn't exist
    :raises APIError: if process dict is invalid

    :return: True on success, False upon failure

    """

PyCharm 的文档字符串模板有什么用？我如何有效地使用它？

What is the use of PyCharm's docstring template? How do I use it effectively?

python

documentation

coding-style

docstring

pycharm