Sphinx Autodoc 从文档字符串中跳过成员

Question

我正在用 Sphinx 记录一个课程，并且简单地想跳过其中一个课程成员：

class StatusUpdateAdapter(logging.LoggerAdapter):
    """
    """
    def __init__(self, status_update_func, logger, extra={}):
        """
        """
        pass

    def log(self, *args, **kwargs):
        pass

如何使 sphinx 不记录日志成员？如果可能的话，我想在 StatusUpdateAdapter 中执行此操作或记录文档字符串。

Answer 1

您现在（从版本 0.6 开始）可以使用

:exclude-members:

从文档中排除特定成员：

支持成员文档的指令还有一个 except-members 选项可用于排除单个成员名称 如果要记录所有成员，请从文档中获取。

0.6版本新增功能。

来源：http://www.sphinx-doc.org/en/stable/ext/autodoc.html

在您的具体情况下，您可以将

:exclude-members: log

添加到您的

.rst

文件中。

Answer 2

您可以使用

:meta private:

以便 Sphinx 将该方法视为私有方法，如果您将 Sphinx 配置为隐藏私有方法，该方法将被隐藏。

记录于https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directives“选项和高级用法”部分：

如果某个成员的文档字符串在其信息字段列表中包含 :meta private: ，则 autodoc 会认为该成员是私有的。例如：

def my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta private:
    """

并且

:private-members:

需要关闭，否则该字段仍然会显示。

Answer 3

似乎没有任何简单的方法可以做到这一点。

作为解决方法，您可以在 RST 文件中尝试类似的操作：

.. autoclass:: StatusUpdateAdapter
   :members: methodA, methodB

但这需要列出您想要手动记录的所有方法，这可能非常费力。如果您正在使用它，它也可能无法与

:inherited-members:

很好地交互。

另一种选择是在您想要记录的每个方法上放置文档字符串，但在

log()

方法上没有文档字符串，然后（如果必要）使用

:no-undoc-members:

。如果您打算记录内部接口或不记录公共接口，这显然是不好的。

最后，Autodoc 会跳过名称以下划线开头的任何内容，除非另有配置 (

:private-members:

)，因此如果您使用以下划线前缀的名称，该方法将不会出现。下划线前缀表示 PEP 8 下的私有接口，这可能符合也可能不符合您的意图。这也可能会在已建立的代码库中造成向后兼容性问题。

Answer 4

我不确定如何使用文档字符串来做到这一点，但您可以使用前置下划线来声明函数/方法“受保护”。 Sphinx 不会引入该函数/方法。

def _log(self, *args, **kwargs):
     pass

Answer 5

有一个类似的问题，并且考虑到（甚至）到今天似乎没有这样的功能，我找到了一个对我有用的解决方法选项：在

autodoc-skip-member()

中创建一个自定义

conf.py

函数。

这允许根据一些输入来定义何时跳过成员，包括对象的类型、对象的名称和对象本身。

有关更多详细信息，请参阅此问题：将 Sphinx autodoc-skip-member 连接到我的函数，特别是 this 答案（返回

None

允许让 Sphinx 使用未明确排除的成员的默认行为）。

Answer 6

为时已晚，但一个丑陋的解决方法是向您想要跳过的公共方法添加一个空文档字符串。像这样：

def log(self, *args, **kwargs):
    ""
    pass