Python：Sphinx namedtuple 文档

Question

我正在尝试记录 namedtuple。当我构建文档时，我收到警告 WARNING: duplicate object description 并且在记录的函数之后出现相同的空函数。例如：

如何删除那些别名？我已经尝试 this solution，将一些函数写入 conf.py 以创建空属性。

此外，我认为值得一提的是，在构建后我得到了使用 :noindex: 的注释，但我不明白我应该在哪里使用它？在我的文档字符串、第一个文件或其他地方？

代码示例：


File = namedtuple("File", ["path", "size", "extension",
                           "adate", "mdate", "links",
                           "user_owner", "group_owner",
                           "inode", "device", "permissions",
                           "depth"])
"""File attributes.

.. py:attribute:: path

    **-** path to the found file

     .. note::
        depending on command-line arguments can be absolute or relative
...

Answer 1

我运行在记录命名元组时遇到同样的问题。这是我的解决方案。

不要在您的 autodoc 指令中使用 :members: 选项。

示例 .rst 文件：

.. documentation for module with namedtuple

Module with namedtuple
======================

.. automodule:: packagename.modulename

.. autoclass:: packagename.modulename.namedtuplename

此外，为了让 Sphinx 获取我的 namedtuple 文档字符串，我必须使用它的 __doc__ 属性。所以使用你的例子：

File = namedtuple("File", ["path", ..., "depth"])
File.__doc__ = """File attributes.

.. :attribute:: path
...
"""

说明

automodule:: 指令获取模块的文档字符串
autoclass:: 指令获取命名元组的文档字符串。

autodoc 的首选（也是常用）方法是使用 :members: 选项并递归记录模块中的所有内容。但是当模块包含 namedtuple 时，使用 :members: 选项（使用任一指令）在文档中生成别名。

对于automodule::，:members:选项使Sphinx递归记录成员：首先是模块的成员（namedtuple的class），然后是成员的成员（ class 的属性）。这会为 namedtuple 创建的 class 选择重复的属性，从而导致别名问题。

对于 autoclass:，:members: 选项再次选择重复的 class 属性，导致别名问题。

因为`_fields`

重复项的潜在机制是文档字符串中记录的 class 属性 已经记录 作为命名元组的 字段名称 (see the docs)。此行为内置于 namedtuples；我不确定如何覆盖它。

要查看此底层机制，请打开 REPL 并列出您的命名元组的 _fields：

>>> File._fields

要查看重复文档问题导致别名消息的位置，请获取有关 namedtuple 的帮助：

>>> help(File)

如果您继续滚动浏览文档，您最终应该会看到如下内容：

 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |
 |  adate
 |      Alias for field number 3
 |
 |  depth
 |      Alias for field number 11

备注

namedtuple 使用与其类型相同的名称也很重要，就像您所做的那样：

File = namedtuple("File", ["path", ..., "depth"])

无论如何这是惯例，但由于它不是必需的，因此值得注意的是，使用不同的名称将导致别名问题 class 而不是 class属性。

Answer 2

sphinx-toolbox 对此提供了解决方案，有关详细信息，请参阅 here。

要使用它，您需要为 pip 用户安装 sphinx-toolbox：

pip install sphinx-toolbox

然后将扩展名插入 conf.py。

extensions = [
    ...
    'sphinx_toolbox.more_autodoc.autonamedtuple',
    ]

没有更多的配置:)

Answer 3

我运行提出了一个我认为比接受的答案更好的解决方案，只是想分享一下：

只需在您的conf.py中写下：

# -- Post process ------------------------------------------------------------
import collections
def remove_namedtuple_attrib_docstring(app, what, name, obj, skip, options):
    if type(obj) is collections._tuplegetter:
        return True
    return skip


def setup(app):
    app.connect('autodoc-skip-member', remove_namedtuple_attrib_docstring)

这会从所有 NamedTuple 类.

中删除使用此“字段别名 ..”自动记录的所有参数

说明

这使用 autodoc 事件 autodoc-skip-member 每次遇到任何类型的成员时都会触发一个处理程序

app.connect('autodoc-skip-member', remove_namedtuple_attrib_docstring) 将处理程序 remove_namedtuple_attrib_docstring 附加到事件
如果成员是 tuplegetter，则处理程序 return 为真，否则 return 默认跳过值

Python：Sphinx namedtuple 文档

Python: Sphinx namedtuple documentation

python

python-sphinx

autodoc

说明

因为`_fields`

备注

Python：Sphinx namedtuple 文档

Python: Sphinx namedtuple documentation

python

python-sphinx

autodoc

说明

因为_fields

备注

因为`_fields`