使用Sphinx时，如何为没有文档字符串的成员编写文档？

Question

使用Sphinx时，如何为没有文档字符串的成员编写文档？

pythonvariablesconstantspython-sphinxmember

5

我正在为我发布的包编写文档，我发现文档越详细，人们使用你的包就越容易（显而易见）。我非常乐意地详细记录我的代码的所有功能和细节。

然而，我完全不知道如何为类级变量编写与Sphinx兼容的文档。特别是，我有一些枚举类需要记录，但是我无法想出一种方法来附加文档到枚举值上。结果是，我的文档中有这些冗长而尴尬的部分，其中除了变量名称外没有文档。

我意识到使用纯文档字符串是不可能的，因为变量没有文档字符串，但是肯定有一些Sphinx的功能可以解决这个问题吧？否则，人们如何记录像常量这样的公开可见值呢？

- alexgolec

请查看此答案以了解如何记录枚举类型。该帖子可能会显得有些牵强，因为它的重点是绕过一个错误，但它包括了在记录枚举成员时你可能需要使用的大多数元素。 - bad_coder

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- bad_coder · Accepted Answer

虽然 Python 变量不能有文档字符串，但使用 Sphinx 的 autodoc 扩展，autodata 和 autoattribute 指令允许记录变量和常量。请注意，在模块级别变量或类成员的情况下使用方式不同。

此外，如果您想在文档中为成员规定一个与编程值不同的值，则最好的方法是使用注释。

autodata 和 autoattribute 支持注释选项。

Sphinx 可以捕获变量声明中的注释并将其包含在文档中（虽然这些注释不是文档字符串，但它们将呈现在文档中）。让我们看一个最小的工作示例：

源文件your_module_name.py:

"""This modules documentation."""

ONE_CONSTANT = "A constant value."
"""Turns out the comment is rendered as a docstring if we put it underneath."""

#: Lets try it like this
TWO_CONSTANTS = 2000


class OneClass:
    """Commenting members of a class."""

    #: Lets try the third comment like this.
    THREE_CONSTANTS = 3000

    #: Lets try the forth comment like this.
    FOUR_CONSTANTS = 4000

对应的是您的模块名称.rst文件：

your\_module\_name module
=========================

.. automodule:: your_module_name
   :members: ONE_CONSTANT, TWO_CONSTANTS

   .. autodata:: ONE_CONSTANT
      :annotation: =this annotation

   .. autoclass:: OneClass
      :members:
      :undoc-members:
      :show-inheritance:

生成的HTML代码为：

最后说明：这可能会强制您调整以前在源代码中用于注释变量的某些约定。此外，如果使用注释，您将不希望将该成员包含在autodata或automodule中，以避免它被包含两次。