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

【问题标题】：Sphinx Autodoc skip member from docstringSphinx Autodoc 从文档字符串中跳过成员
【发布时间】：2015-03-29 06:13:53
【问题描述】：

我正在用 Sphinx 记录一个类，并且想跳过其中一个类成员：

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

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

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

【问题讨论】：

我也需要这个。我已经尝试在文档字符串中包含:exclude-members:，但没有成功。从那以后你找到解决办法了吗？
@GergelyPolonkai 不，这个还没有运气

标签： python python-sphinx autodoc

【解决方案1】：

您可以使用:meta private:，以便 Sphinx 将该方法视为私有方法，如果您将 Sphinx 配置为隐藏私有方法，它将被隐藏。

【讨论】：

【解决方案2】：

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

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

【讨论】：

然而，这使得该方法在源代码中没有记录。这可能（可能会）引起未来维护者的愤怒。
这似乎不起作用。该方法仍然在 sphinx 文档中结束。

【解决方案3】：

我不确定如何使用文档字符串来执行此操作，但您可以使用前置下划线声明函数/方法“受保护”。 Sphinx 不会拉入该函数/方法。

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

【讨论】：

【解决方案4】：

您现在（从 0.6 版开始）可以使用 :exclude-members: 从文档中排除特定成员：

支持成员文档的指令也有一个 exclude-members 选项，可用于排除单个成员名称如果要记录所有成员，则来自文档。

0.6 版中的新功能。

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

在您的具体情况下，您可以将:exclude-members: log 添加到您的.rst 文件中。

【讨论】：

这不是真正回答问题，是吗？有没有办法通过 docstring 做到这一点？将一堆不同类上的各种内部成员硬编码到 sphinx 配置中对于大型项目来说并不实用
没有回答被问到的确切问题，但回答了我的问题:)

【解决方案5】：

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

作为一种解决方法，您可以在 RST 文件中尝试这样的操作：

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

但这需要列出您想要手动记录的所有方法，这可能非常费力。如果您正在使用它，它也可能无法与 :inherited-members: 很好地交互。

另一种选择是在您想要记录的每个方法上放置一个文档字符串，但在log() 方法上没有文档字符串，然后（如果necessary）使用:no-undoc-members:。如果您打算记录内部接口或不记录公共接口，这显然是不好的。

最后，Autodoc 会跳过名称以下划线开头的任何内容，除非另有配置 (:private-members:)，因此如果您使用带下划线前缀的名称，该方法将不会出现。 PEP 8 下的下划线前缀indicates a private interface，这可能与您的意图相符，也可能不相符。这也可能在已建立的代码库中造成向后兼容性问题。

【讨论】：