记录我的Django鳕鱼

Question

我刚用Django开始了一个项目，我想为一个Python函数编写类似下面的javadoc片段。我见过我可以使用Sphinx或RestructedText，但这似乎有点过头了。在Python中通常的方法是什么？在

我的目标不是用我的文档生成一个大的pdf/html，而是让我的IDE（pyCharm）在我调用我的方法时显示文档。在

 /**
  * 
  * @param p1
  * @param p2
  * @param p3
  * @return ...
  */

Answer 1

我在Django和纯Python项目中广泛使用inteljidea/PyCharm。在

正确的方法是使用reStructuredText和Sphinx，后者只有在您想要生成HTML或PDF文档时才可以使用。这也是Python库本身的记录方式。几个月前，我从epydoc切换到reStructuredText，因为后者得到了更好的总体支持。在

您的docstring将如下所示：

def myfunc(p1, p2, p3):
    """myfunc does something interesting.

    some more detail. See :meth:`my_other_func` for more information.

    :param p1: The first parameter.
    :type p1: string
    :param p2: The second parameter.
    :param p3: The third parameter.
    :returns: True if successful, False if not.
    """

    my_code(p1)
    more_code(p2)
    return third_part(p1,p2,p3)

对于基本元素，它与旧的epydoc标准没有太大区别。PyCharm能够解析这些信息，例如在函数体中使用：type:specs来完成。在

Answer 2

如PyCharm webhelp on supported docstring formats中所述，您将有三个选项：

• RestructuredText (rst) for docutils。您不必使用Sphinx生成HTML。你可以让它尽可能轻。在
• epytext格式。（另请参见：epydoc fields documentation）
• 纯文本。这在参数或返回值钩子方面没有提供任何内容。PyCharm只显示普通docstring。在