napoleon 和 autodoc 如何交互记录成员

Question

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

# 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 不要将类变量添加到类定义的底部？尤其令人烦恼的是，它假设它们的值为None，只是因为它们没有默认值。

---

这个问题是在这篇文章的讨论中出现的，其中还包含有关 Sphinx 配置等的评论中的更多上下文。

Answer 1

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

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

例如：

dc module
=========

.. autoclass:: dc.Foo

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

设置以下内容conf.py将导致 Sphinx 将对象的所有成员（带或不带文档字符串）包含在所有未显式指定选项的指令中。

dc module
=========

.. autoclass:: dc.Foo

结果：

Attributes 然而，这提出了一个问题：如果成员在文档字符串部分 中显式指定，但也包含在 autodoc 扩展中，那么 autodoc 和 sphinx-napoleon 扩展会做什么？

文档字符串

Napoleon 解释 autodoc 可以找到的每个文档字符串（...）在每个文档字符串内，特殊格式的部分被解析并转换为 reStructuredText。

例如，将以下文档字符串与上面指定的选项一起使用autodoc_default_options。

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

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

C:\dc.py:dc.Foo.var_a:1 的文档字符串：警告：dc.Foo.var_a 的重复对象描述，dc 中的其他实例，对其中之一使用 :noindex:

C:\dc.py:dc.Foo.var_b:1 的文档字符串：警告：dc.Foo.var_b 的重复对象描述，dc 中的其他实例，对其中之一使用 :noindex:

这里可以注意到一个区别：sphinx-napoleon 将在其自己的文档字符串部分中声明该成员，而 autodoc 将正常将其呈现为其他成员。视觉差异将取决于主题，例如使用classic主题：

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

dc module
=========

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

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