Python napoleon和autodoc如何交互记录成员

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

#我的示例恰好是一个数据类，但是
#普通班是一样的
@数据类
类TestClass：
“”“这是数据类的测试类。
这是docstring描述的主体。
"""
变量int:int
var_str:str

加上一些通用的狮身人面像设置，我在两年前就得到了

我现在得到这个

有没有办法告诉Sphinx不要将类变量添加到类定义的底部？尤其令人恼火的是，它假设它们的值为

None

，仅仅因为它们没有默认值

---

---

此问题是在上的讨论中提出的，在有关Sphinx配置等的注释中还包含了更多的上下文。

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

• 使用

  ：members:

  选项（对于具有docstring的成员）
• 使用

  ：undoc members:

  选项（对于没有docstring的成员）

例如：

dc module
=========

.. autoclass:: dc.Foo

dc module
=========

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

在上面的

.rst

文件中，autodoc指令未设置显式选项，Sphinx将隐式应用从In

conf.py

中获取的选项标志

在

conf.py

中设置以下内容将导致Sphinx在所有未明确指定选项的指令中包含对象的所有成员（带或不带DocString）

#自动文档设置
自动文档\默认\选项={
"委员":对,，
“观察员委员会成员”：正确，
}

结果是：

但是，这提出了一个问题：如果在autodoc扩展包含的

属性中显式指定了成员，但同时也在
中指定了成员，那么autodoc和sphinx napoleon扩展会做什么

文件串


例如，将以下文档字符串与上面在
autodoc\u default\u options
中指定的选项一起使用

导入数据类
@dataclasses.dataclass
Foo类：
“”“Foo的Docstring”
属性：
变量a（str）：一个整数。
var_b（int）：一个字符串。
"""
变量a:str
变量b:int

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

C:\dc.py:dc.Foo.var_a的docstring:1:警告：dc.Foo.var_a的对象描述重复，dc中的其他实例，请使用：noindex:作为其中之一

C:\dc.py:dc.Foo.var_b的docstring:1:警告：dc.Foo.var_b的对象描述重复，dc中的其他实例，请使用：noindex:作为其中之一

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


最后，如果要使用sphinx napoleon记录成员并避免autodoc重复reST声明，同时保留
autodoc\u default\u选项，如图所示，可以在特定指令中显式使用
：exclude members:
选项，例如：

dc module
=========

.. autoclass:: dc.Foo

dc module
=========

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

将仅使用斯芬克斯·拿破仑生成的reST指令记录成员：

我无法用Sphinx 3.2.1和Python 3.8.5重现这一点。当您说：“有没有办法告诉Sphinx不要将类变量添加到类定义的底部？”您的意思是“根本不添加它们”，还是将它们包括在“是的，但不包括在底部”？另外，对于
None
值，您希望的行为是什么？连同等号一起省略？@bad_coder我的意思是根本不添加它们，而且
None
的行为对我来说很奇怪。它们没有值None，如果有的话，它们是未定义的。但是，严格地说，这是一个不同的问题。@mzjn有一个在这里工作：。我尝试了你建议的关于
：undoc成员的@bad\u coder:
，它解决了我的问题。老实说，我从来没有费心去弄清楚autodoc生成的rst中的指令是什么意思。也许
undoc成员的
autodoc\u default\u选项
的默认值过去是
false
，现在是
true
，但我太懒了，无法找到这些信息。请随意发布一个
conf.py
，将其更改回
false
，作为我可以接受的答案=）我可以在
conf.py
中配置排除成员吗，还是每次运行sphinx apidoc时都需要更新.rst？@Arne我写了一篇关于使用
sphinx apidoc
时设置默认autodoc选项的困难的文章。catch是
sphinx apidoc
从环境变量中获取默认选项，而不是作为命令行参数…至于其余的，
：排除成员：
可以在
autodoc\u default\u标志中设置。正确的选择是将最常用的选项设置为默认值，只要您想在
.rst
指令中直接设置该选项的规则集异常。感谢您的深入解释和资源链接=）