python - 拿破仑和自动文档如何交互文档成员

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 将隐式应用从autodoc_default_flagsin 中获取的选项标志conf.py。

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

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

结果：

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

文档字符串

Napoleon 解释 autodoc 可以找到的每个文档字符串（...）在每个文档字符串中，特殊格式的部分被解析并转换为 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: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 将在其自己的docstring 部分中声明该成员，而 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 指令记录成员：