拿破仑和奥多克如何互动记录成员 [英] How napoleon and autodoc interact documenting members

问题描述

我注意到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设置，我大约在两年前就得到了这个

我现在收到了这个

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

---

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

推荐答案

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

• 使用: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,
}

结果：

然而，这引发了一个问题：如果成员在Attributesdocstring section中明确指定，但也包含在AutoDoc扩展中，那么AutoDoc和狮身人面像-拿破仑扩展会做什么？

文档字符串

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：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：作为其中之一

这里可以注意到一个不同之处：斯芬克斯-拿破仑将在自己的docstring section中声明该成员，而Autodoc会正常地将其呈现为其他成员。视觉差异将取决于主题，例如使用classic主题：

最后，如果您希望使用sphinx-napoleondocstring sections来记录成员，并在保留autodoc_default_options的同时避免来自AutoDoc的重复REST声明，则可以显式使用该特定指令中的选项，例如：

dc module
=========

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

将仅使用狮身人面像-拿破仑生成的REST指令记录成员：

这篇关于拿破仑和奥多克如何互动记录成员的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！