用docstring记录Python函数，使其在原始形式下可读且能生成良好的sphinx输出

Question

我有一个用Python写的应用程序。我正在使用Sphinx和它的autodoc扩展来生成文档。在记录函数参数时，我发现有两种主要的写法选择：

选项 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 不能像选项 1 那样放在“Args”这样的标题下，否则会导致显示效果出错。虽然选项 2 的显示效果比选项 1 好得多，但它让实际的文档字符串变得不太易读。为什么 param 需要写一万遍呢？选项 1（来自谷歌的Python风格指南）提供了更好的文档字符串，但显示效果却很差。有没有一种标准的写法，可以同时生成干净的原始文档字符串和良好的显示效果呢？

Answer 1

我不太明白你说的意思，

注意，选项2不能放在像“参数”这样的标题下。

但实际上，选项2是标准做法。它提供了你需要的所有内容来记录你的函数或方法等。而且最重要的是，它的语法是Sphinx文档工具的一部分，任何符合标准的解析器都能正确且一致地显示它。例如，看看我们如何用选项2来记录这个大类的方法（这段是从一个rst文件复制过来的，但你可以很容易地调整它，粘贴到文档字符串里）：

.. py:method:: create(**fields)
    :module: redmine.managers.ResourceManager
    :noindex:

    Creates new issue resource with given fields and saves it to the Redmine.

    :param project_id: (required). Id or identifier of issue's project.
    :type project_id: integer or string
    :param string subject: (required). Issue subject.
    :param integer tracker_id: (optional). Issue tracker id.
    :param string description: (optional). Issue description.
    :param integer status_id: (optional). Issue status id.
    :param integer priority_id: (optional). Issue priority id.
    :param integer category_id: (optional). Issue category id.
    :param integer fixed_version_id: (optional). Issue version id.
    :param boolean is_private: (optional). Whether issue is private.
    :param integer assigned_to_id: (optional). Issue will be assigned to this user id.
    :param watcher_user_ids: (optional). User ids who will be watching this issue.
    :type watcher_user_ids: list or tuple
    :param integer parent_issue_id: (optional). Parent issue id.
    :param start_date: (optional). Issue start date.
    :type start_date: string or date object
    :param due_date: (optional). Issue end date.
    :type due_date: string or date object
    :param integer estimated_hours: (optional). Issue estimated hours.
    :param integer done_ratio: (optional). Issue done ratio.
    :param list custom_fields: (optional). Custom fields in the form of [{'id': 1, 'value': 'foo'}].
    :param uploads:
      .. raw:: html

          (optional). Uploads in the form of [{'': ''}, ...], accepted keys are:

      - path (required). Absolute path to the file that should be uploaded.
      - filename (optional). Name of the file after upload.
      - description (optional). Description of the file.
      - content_type (optional). Content type of the file.

    :type uploads: list or tuple
    :return: Issue resource object

这段代码会被渲染成：

我希望你能同意，它在原始和渲染后的形式中都能产生非常相似且易读的结果。

Answer 2

你可以使用numpy的文档字符串格式和numpydoc来写出清晰易读的文档字符串，同时还能生成漂亮的sphinx输出。

首先，安装numpydoc：

pip install numpydoc

然后在你的conf.py文件的扩展部分添加'numpydoc'。

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

这样你的文档字符串就会遵循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

在sphinx中显示效果：