将 Sphinx 与 reStructuredText 格式的文档字符串一起使用

Question

根据 Sphinx 的 writing docstrings tutorial，可以利用 Sphinx 的 autodoc 扩展来自动生成文档。我们可以使用 Sphinx 格式、Google 或 Numpy（后两者具有 napoleon 扩展名）来编写文档字符串。

是否可以用 reStructuredText 格式编写文档字符串？

例如：

"""[Summary]

Extended description of function.

:param int arg1: Description of arg1.
:param str arg2: Description of arg2.
:raise: ValueError if arg1 is equal to arg2
:return: Description of return value
:rtype: bool
"""

为了比较，这是 Sphinx 原生格式：

"""[Summary]

:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)
...
:raises [ErrorType]: [ErrorDescription]
...
:return: [ReturnDescription]
:rtype: [ReturnType]
"""

Comparison of docstrings

Answer 1

感谢@mzjin 在评论中的回答：this link描述了这是可能的，因为v0.4。

link 中给出了以下示例，这正是我要找的。

py:function:: send_message(sender, recipient, message_body, [priority=1])
   """
   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring
   """

Answer 2

这两种格式其实是一样的。这可能令人困惑，但所谓的 Info field lists can be considered the reST docstring syntax. If you look carefully at the version number it's been around since Sphinx version 0.4, next if we look at the current Sphinx change list it remits to a change list that predates version 1.0... 最早提到的是：

Release 0.4 (Jun 23, 2008)

==========================

Sphinx now interprets field lists with fields like :param foo: in description units.

如果我们想进一步回溯到 reST docstring 语法的定义，Doc-SIG - Python Documentation Special Interest Group would be the way to go, but a good enough overview is given by PEP 256 - Rationale 日期为 01-Jun-2001 的档案。从那时起出现的最常被引用的文件只提出了一个松散的建议：

PEP 257 -- Docstring Conventions

Python is case sensitive and the argument names can be used for keyword arguments, so the docstring should document the correct argument names. It is best to list each argument on a separate line.

总而言之，reST docstring 语法仅包括使用 reST Field Lists!（NumPy 和 Google 风格只是不同的写作风格reST 字段列表)!

Field List - reStructuredText Markup Specification

Field lists are mappings from field names to field bodies,

(...)

The interpretation of individual words in a multi-word field name is up to the application. The application may specify a syntax for the field name.

Syntax diagram (simplified):
+--------------------+----------------------+
| ":" field name ":" | field body           |
+-------+------------+                      |
        | (body elements)+                  |
        +-----------------------------------+

由应用程序指定字段名称的语法；所以 Sphinx 文档生成器为问题中的 2 个示例语法指定的是它们是等效的（如果您更改为不同的文档生成器，这不一定成立）。

将 Sphinx 与 reStructuredText 格式的文档字符串一起使用

Utilizing Sphinx with reStructuredText formatted docstrings

python

restructuredtext

docstring

python-sphinx