记录我的Django代码

Question

我刚刚开始使用Django开发一个项目，我想为Python函数编写类似下面的javadoc片段。我已经看到我可以使用Sphinx或reStructuredText，但它似乎过度使用。在Python中执行此操作的常规方法是什么？

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

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

Answer 1

我在Django和普通的Python项目中广泛使用IntellJ IDEA / 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只显示纯文档字符串。