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

我不太明白你的意思

Note that option 2 cannot be nested under a header like "Args"

但实际上，选项2是的标准。它提供了记录函数/方法等所需的一切，最重要的是，它的语法是Sphinx文档工具的一部分，任何兼容的解析器都可以正确地、类似地呈现它。例如，考虑如何使用选项2记录这个大类方法（这是一个来自rst文件的copy'n'paste，但是您可以很容易地将其调整为粘贴到docstring中）：

.. 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

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

安装numpydoc:

pip install numpydoc

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

^{pr2}$

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

^{3}$

在狮身人面像中：