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

Question

我正在使用Sphinx记录一个类，只想跳过其中的一个成员：

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

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

我该如何让Sphinx不记录log成员？如果可能的话，我想在StatusUpdateAdapter或log docstring中实现这一点。

- Colton Leekly-Winslow

---

我也需要这个。我已经尝试在docstring中包含:exclude-members:，但没有成功。自那以后你有找到解决方案吗？ - GergelyPolonkai

@GergelyPolonkai 没有，这个还没有成功。 - Colton Leekly-Winslow

Answer 1

自版本0.6起，您现在可以使用:exclude-members:来排除特定成员的文档：

支持成员文档的指令还有一个exclude-members选项，如果要对所有成员进行文档编制，可以用它来排除单个成员名称。

版本0.6中新增。

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

在您的特定情况下，您需要在.rst文件中添加:exclude-members: log。

- OdinX

---

这并没有真正回答问题，有没有一种通过docstring实现这个的方法？在许多不同的类中硬编码大量内部成员到sphinx配置文件中并不适用于较大的项目。 - E. T.

没有回答被问到的确切问题，但是回答了我所提出的问题 :) - Joao Coelho

Answer 2

你可以使用:meta private:，这样Sphinx会将该方法视为私有方法，并且如果你配置了Sphinx隐藏私有方法，它将被隐藏起来。

在https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directives的"Options and advanced usage"部分有详细文档。

autodoc considers a member private if its docstring contains :meta private: in its Info field lists. For example:

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

    :meta private:
    """

而且:private-members:需要关闭，否则该字段仍将显示。

- leszek.hanusz

Answer 3

看起来没有简单的方法来实现这个目标。

作为一种解决方法，您可以尝试在RST文件中使用类似以下内容的方法：

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

但这需要手动列出您想记录的所有方法，这可能非常费力。此外，如果您正在使用:inherited-members:，它可能与之交互不良。

另一种选择是在您想要记录的每个方法上放置一个docstring，但是在log()方法上没有docstring，然后（如果必要）使用:no-undoc-members:。如果您打算记录内部接口或不记录公共接口，则显然不适用于此选项。

最后，Autodoc会跳过任何名称以下划线开头的内容（除非另有配置：:private-members:），因此，如果您使用下划线前缀名称，则该方法将不会显示。在PEP 8下，下划线前缀表示私有接口，这可能与您的意图不符。这也可能在已建立的代码库中创建向后兼容性问题。

- Kevin

Answer 4

我不确定如何使用文档字符串来实现，但你可以在函数/方法名前加上下划线来声明为“受保护的”。这样，Sphinx就不会将该函数/方法包含在内。

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

- Mr. Heuristic

Answer 5

我曾经遇到过类似的问题，但即使到今天为止，似乎也没有这样的功能。不过我找到了一个可行的解决方案：在conf.py中创建一个自定义的autodoc-skip-member()函数。

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

有关更多详细信息，请参见此问题：将Sphinx autodoc-skip-member连接到我的函数，特别是this答案（返回None允许让Sphinx使用未明确排除的成员的默认行为）。

- sarusso

Answer 6

虽然有些晚了，但一个丑陋的解决方法是在你想要跳过的公共方法中添加一个空的文档字符串。就像这样：

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

- Petar Donchev

---

然而，这样做会使该方法在源代码中未记录。这可能会（很可能会）招致未来维护者的愤怒。 - S3DEV

似乎不起作用。该方法仍然出现在Sphinx文档中。 - gerrit