拿破仑和奥多克怎么互动记录成员

本教程将介绍拿破仑和奥多克如何互动记录成员的处理方法,这篇教程是从别的地方看到的,然后加了一些国外程序员的疑问与解答,希望能对你有所帮助,好了,下面开始学习吧。

拿破仑和奥多克怎么互动记录成员 教程 第1张

问题描述

我注意到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指令记录成员:

好了关于拿破仑和奥多克怎么互动记录成员的教程就到这里就结束了,希望趣模板源码网找到的这篇技术文章能帮助到大家,更多技术教程可以在站内搜索。