python - 记录我的 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，因为对后者的一般支持要好得多。

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

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 中关于支持的文档字符串格式所提到的，您将拥有三个选项：

• docutils 的 RestructuredText (rst)。您不必使用 Sphinx 来生成 HTML。您可以随心所欲地保持它的轻量级。
• 电子文本格式。（另见：epydoc 字段文档）
• 纯文本。这在参数或返回值挂钩方面没有提供任何东西。PyCharm 只会显示纯文档字符串。