如何将 :special-members: 应用于自动模块指令中的一个 class ？

Question

我正在使用 autodoc 和 napoleon 为 Python 2.7 项目整理 Sphinx 驱动 (v1.3.1) 文档。在我想用单个 automodule:: 指令记录的一个模块中，我有一个特定的 class，我想对其应用 :special-members: 标志。用 :special-members: 标记 automodule:: 会显示模块中 所有内容 的特价，这不好。

我该怎么做？

添加带有 :special-members: 标记的 autoclass:: 指令仍然会留下“非专业”文档作为 automodule:: 内容的一部分，从而导致内容重复。

我想我可以在 automodule:: 上的 :members: 指令中明确地键入模块中的所有 classes，但我的特殊目标除外，但后来我'每次我向模块添加或删除 class 时，我都必须记住更新该列表。

Answer 1

此问题的解决方案是排除您希望在 automodule 中应用不同选项的成员。然后将它们包含在自己的指令中，在该指令上设置您想要的特定选项。

以下示例从 automodule 指令中排除 ClassB。之后 ClassB 包含在 automodule 的上下文中，并带有自己的 autoclass 指令。在 :special-members: 选项下仅设置您想要显示的成员。

对应的.rst文件：

selective module
================

.. automodule:: selective
    :members:
    :exclude-members: ClassB

    .. autoclass:: ClassB
        :special-members: __init__, __special_func_two__

对应的.py文件：

"""This modules docstring."""


class ClassA:
    """ClassA docstring."""

    def __special_func_one__(self, two):
        """Special method docstring."""
        self.two = two

    def __init__(self, one):
        """Special method docstring."""
        self.one = one


class ClassB:
    """ClassB docstring."""

    def __special_func_two__(self, two):
        """Special method docstring."""
        self.two = two

    def __special_func_three__(self, three):
        """Special method docstring."""
        self.three = three

    def __init__(self, one):
        """Special method docstring."""
        self.one = one

这最大限度地减少了您必须键入的异常数量，因为默认规则仍然通常适用于模块的其余成员，除非您另有说明。在大多数 IDE 中，此解决方案还将重构对 Python 源代码所做的更改。

显示的精确解 special-members 和 private-members 未包含在 conf.py 内的 autodoc_default_options 中。相关的 sphinx.ext.napoleon 设置被设置为 napoleon_include_special_with_doc = False。但是，个别指令设置仍然优先于以前的一般配置。

如何将 :special-members: 应用于自动模块指令中的一个 class ？

How can I apply :special-members: to just one class inside an automodule directive?

python

double-underscore

python-sphinx

autodoc

sphinx-napoleon