Python 记录我的Django代码

我刚刚用Django启动了一个项目，我想为Python函数编写类似下面的javadoc代码片段。我知道我可以使用斯芬克斯或重组文本，但这似乎有点过分了。在Python中执行此操作的正常方式是什么

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

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

如中所述，您将有三个选项：

• 。您不必使用Sphinx来生成HTML。你可以随意保持它的轻盈
• 格式。（另见：）
• 纯文本。这在参数或返回值挂钩方面不提供任何内容。PyCharm将仅显示普通docstring

---

我在Django和普通Python项目上广泛使用IntellJ IDEA/PyCharm

方法是明确地重新构造dtext和Sphinx，只有当您想要生成HTML或PDF文档时，才使用后者。这也是Python库本身的文档记录方式。几个月前，我从epydoc转到了StructuredText，因为后者得到了更好的普遍支持

您的文档字符串如下所示：

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:spec在函数体中完成