使用docstring记录Python函数,该docstring既可以原始形式读取,也可以产生良好的sphinx输出

Question

我有一个Python应用程序.我正在使用带有autodoc扩展的Sphinx来为它生成文档.在记录函数参数时,我看到两个主要选项:

选项1

def makeBaby(mommy, daddy):
  """Execute the miracle of life.

  Args:
    mommy: description of mommy
    daddy: description of daddy
  """

选项2

def makeBaby(mommy, daddy):
  """Execute the miracle of life.

  :param mommy: description of mommy
  :param daddy: description of daddy
  """

请注意,选项2不能嵌套在"Args"之类的标题下,如选项1所示,不会破坏渲染输出.选项2具有比选项1更好的渲染输出,但使实际的文档字符串更不易读.为什么param需要写成万亿次？选项1(来自Google的Python样式指南)提供了更好的文档字符串,但渲染的输出很差.是否存在函数docstrings的标准,它既可以生成干净的原始文档字符串,又可以生成良好的渲染输出？

Answer 1

您可以使用numpy docstrings格式和numpydoc来获得清晰可读的文档字符串,以及一个很好的sphinx输出.

安装numpydoc:

pip install numpydoc

添加'numpydoc'到扩展程序中的conf.py.

extensions = ['sphinx.ext.autodoc',
              'numpydoc']

然后你的docstrings将遵循numpy格式.您可以在文档中阅读有关布局的更多信息.对于你的例子:

def makeBaby(mommy, daddy):
   """Execute the miracle of life.

   Parameters
   ----------
   mommy : description of mommy
   daddy : description of daddy

   Returns
   -------
   baby : mommy + daddy

   """
   return mommy + daddy

在狮身人面像: