选择性地禁用继承的成员答案

【问题标题】：Selectively disable inherited-members选择性地禁用继承的成员
【发布时间】：2021-08-03 18:35:17
【问题描述】：

在与 Sphinx 中糟糕的默认设置进行了多次斗争之后，我终于找到了一种在子类文档中显示继承方法的方法。不幸的是，这个选项是全局的......

autodoc_default_options = {
    ...
    'inherited-members': True,
}

有没有办法注释任何给定的类以防止继承的方法和字段显示在该文档中？

如果没有办法基于继承，有没有办法简单地列出我不想在其文档字符串中为给定类记录的所有方法？

我很好......好吧，我会哭一会儿，但如果我必须列出需要记录的方法而不是将我不想要的方法列入黑名单，我会活下去。

我知道我可以将 :meta private: 放在方法定义中以规避它包含在文档中（有点，不是真的，但我们假设它有效），但在继承方法的情况下，我无法将文档字符串附加到.

请注意，任何涉及手动编写.. automodule:: 部分的“解决方案”都不是解决方案——必须生成这些解决方案。

【问题讨论】：

“那些必须生成” - 你指的是 sphinx-apidoc 吗？
@mzjn 是的。我愿意。
sphinx-apidoc 仅输出 automodule 指令。如果您想要特定类的文档例外，可以使用autoclass 完成。像这样的东西：stackoverflow.com/q/33704275/407651.
@mzjn 这不是我想要的......我希望在附加到源代码的文档字符串中发生这种情况。我无法触摸 sphinx-apidoc 生成的代码。如果我要写那个，那么使用 apidoc 有什么意义呢？实在是太让人头疼的没用的工具了，不过已经经历了这个头疼的事情，我还不太愿意完全放弃它……
目前我没有任何其他建议。请注意，除非您的项目非常不稳定，否则没有必要一遍又一遍地运行 sphinx-apidoc。运行一次，进行调整，然后将文件添加到版本控制中。见stackoverflow.com/a/28481785/407651。

标签： python python-sphinx

【解决方案1】：

好吧，我想出了如何解决一半的问题。为大量胶带做好准备......

因此，这里有一个示例，说明如何在直接或间接扩展 Exception 类的所有内容中禁用继承字段：

def is_error(obj):
    return issubclass(obj, Exception)


conditionally_ignored = {
    '__reduce__': is_error,
    '__init__': is_error,
    'with_traceback': is_error,
    'args': is_error,
}

def skip_member_handler(app, objtype, membername, member, skip, options):
    ignore_checker = conditionally_ignored.get(membername)
    if ignore_checker:
        frame = sys._getframe()
        while frame.f_code.co_name != 'filter_members':
            frame = frame.f_back

        suspect = frame.f_locals['self'].object
        return not ignore_checker(suspect)
    return skip


def setup(app):
    app.connect('autodoc-skip-member', skip_member_handler)

将以上内容放入您的config.py。这意味着您正在使用autodoc 来生成文档。

最后，我并没有从正在记录的类的文档字符串中控制这种行为。这只是工作量太大，autodoc、Sphinx 构建器、生成的输出等存在太多错误。只是不值得。

但是，一般的想法是在读取源时类似地添加一个事件处理程序，从文档字符串中提取信息，用没有必要信息的修补文档字符串替换文档字符串，将提取的信息保存在某个地方，直到跳过处理程序调用，然后执行跳过。但是，就像我说的那样，这条线有太多的东西被打破了。

另一种方法是发出 XML，用 XSLT 对其进行修补并将其反馈给Docutils，但在编写 XML 生成器时已损坏（它向 XML 添加了命名空间属性，但它没有声明命名空间。 ..) 老经典。

另一种方法是处理事件，例如生成文档并解析引用。不幸的是，到那时，您将丢失诸如您正在使用的事物类型、原始文档字符串等信息。您实际上是在修补 HTML，但结构非常复杂。

【讨论】：