Question

我有一个模块errors.py，其中定义了几个全局常量（注意：我知道Python没有常量，但我已经按惯例使用UPPERCASE定义了它们。）

"""Indicates some unknown error."""
API_ERROR = 1

"""Indicates that the request was bad in some way."""
BAD_REQUEST = 2

"""Indicates that the request is missing required parameters."""
MISSING_PARAMS = 3

使用reStructuredText如何记录这些常量？正如你所看到的，我已经在它们上面列出了一个文档字符串，但是我没有找到任何表明这样做的文档，我只是猜测它。

Answer 1

不幸的是，变量（和常量）没有文档字符串。毕竟，变量只是一个整数的名称，并且您不希望像对函数或类对象那样将文档字符串附加到数字1。

如果您查看stdlib中的几乎任何模块，例如pickle，您将看到他们使用的唯一文档是注释。是的，这意味着help(pickle)只显示了这一点：

DATA
    APPEND = b'a'
    APPENDS = b'e'
    …

......完全无视评论。如果您希望您的文档显示在内置帮助中，则必须将它们添加到模块的文档字符串中，这不完全是理想的。

但是Sphinx可以做的不仅仅是内置的帮助。您可以将其配置为提取常量的注释，或使用autodata半自动执行注释。例如：

#: Indicates some unknown error.
API_ERROR = 1

任何赋值语句之前的多个#:行，或语句右侧的单个#:注释，与autodoc选取的对象上的文档字符串有效地相同。其中包括处理内联rST，以及为变量名自动生成rST头;没有什么额外的事情可以做到这一点。

作为旁注，您可能需要考虑使用enum而不是像这样的单独常量。如果你没有使用Python 3.4（你可能还没有...），那么有一个{+ 3}}包用于3.2+或backport.enum（它不相同，但它是相似的，因为它对于2.6 +来说，它是stdlib模块的主要灵感。

枚举实例（不是flufl.enum，但是stdlib / backport版本）甚至可以有文档字符串：

class MyErrors(enum.Enum):
    """Indicates some unknown error."""
    API_ERROR = 1

    """Indicates that the request was bad in some way."""
    BAD_REQUEST = 2

    """Indicates that the request is missing required parameters."""
    MISSING_PARAMS = 3

虽然遗憾的是它们没有显示在help(MyErrors.MISSING_PARAMS)中，但它们是Sphinx autodoc可以接收的文档字符串。

Answer 2

如果你在变量之后放了一个字符串，那么sphinx将把它作为变量的文档。我知道它有效，因为我在整个地方都这样做。像这样：

FOO = 1 """ Constant signifying foo. Blah blah blah... """ # pylint: disable=W0105

pylint指令告诉pylint避免将文档标记为无效的语句。

Answer 3

您可以使用散列+冒号来记录属性（类或模块级别）。

  #: Use this content as input for moo to do bar
  MY_CONSTANT = "foo"

这将是一些文档生成器。

这里有一个例子，找不到更好的Sphinx document module properties

Answer 4

这是一个较旧的问题，但我注意到缺少相关的答案。

或者您可以通过.. py:data::在模块的docstring中包含常量的描述。这样，文档也可以通过交互式帮助获得。狮身人面像会很好地渲染它。

"""
Docstring for my module.

.. data:: API_ERROR

    Indicates some unknown error.

.. data:: BAD_REQUEST

    Indicates that the request was bad in some way.

.. data:: MISSING_PARAMS

    Indicates that the request is missing required parameters.
"""

Answer 5

我觉得你在这里运气不好。

Python不直接支持变量上的文档字符串：没有属性可以附加到变量并以交互方式检索，如模块，类和函数的__doc__属性。

Source

Answer 6

之所以写这篇文章，是因为到目前为止，我还没有看到这个选项：

您还可以将常量定义为在调用时仅返回所需常量值的函数，例如：

def get_const_my_const() -> str:
    """Returns 'my_const'."""
    return "my_const"

这样，一方面，它们将变得“更加稳定”（不必担心重新分配），并且它们将为常规文档以及其他任何功能提供机会。

Answer 7

Sphinx Napoleon Python documentation extension允许在“属性”部分中记录模块级变量。

每个https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html：

Attributes
----------
module_level_variable1 : int
    Module level variables may be documented in either the ``Attributes``
    section of the module docstring, or in an inline docstring immediately
    following the variable.

    Either form is acceptable, but the two should not be mixed. Choose
    one convention to document module level variables and be consistent
    with it.

Answer 8

以下内容在Sphinx 2.4.4中对我有用：

在foo.py中：

API_ERROR = 1
"""int: Indicates some unknown error."""

然后记录下来：

.. automodule:: foo.py 
    :members:

如何在Python中记录模块常量？

8 个答案: