用一个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

^{pr2}$

注意，选项2不能像选项1那样嵌套在“Args”这样的头下，而不中断呈现的输出。选项2的呈现输出比选项1好得多，但使实际的docstring更不可读。为什么param需要写一万亿次？选项1（来自Google的Python样式指南）提供了更好的docstring，但是呈现的输出很差。函数docstrings是否有一个标准既能产生干净的原始docstring，又能产生良好的呈现输出？在

Answer 1

您可以使用numpydocstrings格式和numpydoc来获得清晰可读的docstrings，外加一个漂亮的sphinx输出。在

安装numpydoc:

pip install numpydoc

将'numpydoc'添加到配置文件在扩展中。在

^{pr2}$

那么您的docstring将遵循numpy格式。您可以在docs中阅读有关布局的更多信息。例如：

^{3}$

在狮身人面像中：