1

我正在为 Python 2.7 项目使用autodoc和napoleon. 在我想用一个automodule::指令记录的一个模块中，我有一个要应用:special-members:标志的特定类。标记automodule::with会显示模块中所有内容:special-members:的特价，这不好。

我怎样才能做到这一点？

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

我想我可以在 的:members:指令中明确键入模块中的所有类，但我的特殊目标类除外automodule::，但是我必须记住每次在模块中添加或删除一个类时更新该列表。

4

1 回答 1

1

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

以下示例ClassB从automodule指令中排除。AfterwardsClassB包含在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不包含在autodoc_default_options里面conf.py。相关的 sphinx.ext.napoleon 设置被设置为napoleon_include_special_with_doc = False. 但是，单个指令设置仍将优先于以前的常规配置。

于 2020-09-10T16:40:17.147 回答