napoleon 和 autodoc 如何交互记录成员

Question

我注意到 Sphinx 呈现 class 描述的行为发生了变化。鉴于此代码

# my example happens to be a dataclass, but the behavior for 
# regular classes is the same
@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.
    """
    var_int: int
    var_str: str

加上一些通用的 Sphinx 设置，大约两年前我曾经得到过这个

我现在得到这个

有没有办法告诉 Sphinx 不要将 class 变量添加到 class 定义的底部？特别烦人的是，它假定它们的值为 None，只是因为它们没有默认值。

这个问题是在的讨论中提出的，它在关于 Sphinx 配置等的评论中也包含了更多的上下文。

Answer 1

对象成员包含在 autodoc 指令中，具体取决于：

使用 :members: 选项（对于具有文档字符串的成员）。
使用 :undoc-members: 选项（对于没有文档字符串的成员）。

例如：

dc module
=========

.. autoclass:: dc.Foo

在上面的 .rst 文件中，autodoc 指令没有显式设置选项，Sphinx 将做的是隐式应用从 conf.py 中的 autodoc_default_flags 中获取的选项标志。

在 conf.py 中设置以下内容会导致对象的所有成员（有或没有文档字符串）被 Sphinx 包含在所有未明确指定选项的指令中。

# autodoc settings
autodoc_default_options = {
    'members':          True,
    'undoc-members':    True,
}

结果：

但是，这提出了一个问题：如果在 Attributes docstring section 中明确指定了成员，那么 autodoc 和 sphinx-napoleon 扩展会做什么 [=69] =] 包含在 autodoc 扩展中？

Docstrings

Napoleon interprets every docstring that autodoc can find (...) Inside each docstring, specially formatted Sections are parsed and converted to reStructuredText.

例如，将以下文档字符串与上面 autodoc_default_options.
中指定的选项一起使用
import dataclasses @dataclasses.dataclass class Foo: """Docstring for Foo Attributes: var_a (str): An integer. var_b (int): A string. """ var_a: str var_b: int

在这种情况下，成员将被声明两次，每个扩展一次，相应的 reST 声明将作为副本生成。具有重复的 reST 声明将导致通常的警告：

C:\dc.py:docstring of dc.Foo.var_a:1: WARNING: duplicate object description of dc.Foo.var_a, other instance in dc, use :noindex: for one of them

C:\dc.py:docstring of dc.Foo.var_b:1: WARNING: duplicate object description of dc.Foo.var_b, other instance in dc, use :noindex: for one of them

这里有一个区别可以注意：sphinx-napoleon 将在其自己的 docstring section 中声明该成员，而 autodoc 会将其正常呈现为其他成员。视觉差异将取决于主题，例如使用 classic theme:

最后，如果您想使用 sphinx-napoleon docstring sections 记录成员并避免来自 autodoc 的重复 reST 声明，同时保持 autodoc_default_options 如图所示，您可以显式使用 :exclude-members: 该特定指令中的选项，例如：

dc module ========= .. autoclass:: dc.Foo :exclude-members: var_a, var_b

将仅使用 sphinx-napoleon 生成的 reST 指令记录成员：

napoleon 和 autodoc 如何交互记录成员

How napoleon and autodoc interact documenting members

python

python-sphinx

autodoc

sphinx-napoleon

python-dataclasses