python 我怎样才能防止Sphinx将“object”列为基类?

rryofs0p  于 2023-01-08  发布在  Python
关注(0)|答案(4)|浏览(89)

我有这样的课:

class Class:
    pass

sphinx生成的文档(如果有必要,我使用了autodoc扩展)如下所示:

  • 类 * 包。

基础:对象
object继承而来的信息对读者来说没有什么用处,因此我不想在我的文档中介绍它,我希望看到的输出如下:

  • 类 * 包。

有没有办法从基类列表中排除object

vcudknz3

vcudknz31#

这实际上已经深深嵌入到autodoc源代码中,无法关闭:

bases = [b.__module__ in ('__builtin__', 'builtins') and
         u':class:`%s`' % b.__name__ or
         u':class:`%s.%s`' % (b.__module__, b.__name__)
         for b in self.object.__bases__]
self.add_line(u'   ' + _(u'Bases: %s') % ', '.join(bases), sourcename)

object不做任何特殊处理;没有内置的方法将其从列表中排除。
我能找到的最好的(自动)解决方案是monkeypatch autodoc。
将其添加到conf.py可实现所需的行为:

# ClassDocumenter.add_directive_header uses ClassDocumenter.add_line to
#   write the class documentation.
# We'll monkeypatch the add_line method and intercept lines that begin
#   with "Bases:".
# In order to minimize the risk of accidentally intercepting a wrong line,
#   we'll apply this patch inside of the add_directive_header method.

from sphinx.ext.autodoc import ClassDocumenter, _

add_line = ClassDocumenter.add_line
line_to_delete = _(u'Bases: %s') % u':class:`object`'

def add_line_no_object_base(self, text, *args, **kwargs):
    if text.strip() == line_to_delete:
        return

    add_line(self, text, *args, **kwargs)

add_directive_header = ClassDocumenter.add_directive_header

def add_directive_header_no_object_base(self, *args, **kwargs):
    self.add_line = add_line_no_object_base.__get__(self)

    result = add_directive_header(self, *args, **kwargs)

    del self.add_line

    return result

ClassDocumenter.add_directive_header = add_directive_header_no_object_base
xiozqbni

xiozqbni2#

对于2022年6月和Sphinx v5.0.1,Aran-Fey的回答有点过时;在我的例子中,有效的解决方案是替换这一行:

line_to_delete = _(u'Bases: %s') % u':class:`object`'

用这个

line_to_delete = _(u'Bases: %s') % u':py:class:`object`'
lx0bsm1f

lx0bsm1f3#

    • 免责声明**:这可能不是最好或最优雅的解决方案,因为您拥有的普通类越多(只有子类object),您必须手动预处理每个类所做的工作就越多。

如果你使用autoclass指令来记录类,就不要使用:show-inheritance:选项。如果你使用automodule来为所有模块成员生成文档,关闭:show-inheritance:将不会有帮助,因为模块中的每个类都不会记录基类。因此,我将使用以下选项:

    • 第1步**:在模块外记录类,不使用:show-inheritance:,如下所示:
my\.mod module
--------------

.. automodule:: my.mod
   :members:
   :undoc-members:
   :show-inheritance:

.. autoclass:: Class
   :members:
   :undoc-members:
    • 步骤2**:通过autodoc-skip-member钩子将Class类从conf.py中的模块automodule文档中过滤出来:
def skip_some_classes(app, what, name, obj, skip, options):
    return skip or name in ('Class',)  # define some better condition here

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

这样,除Class之外的所有模块成员都将使用:show-inheritance:选项进行处理,而Class则单独处理。

0yycz8jy

0yycz8jy4#

对我来说,工作真的很简单的解决方案。

from sphinx.ext import autodoc

class MockedClassDocumenter(autodoc.ClassDocumenter):
    def add_line(self, line: str, source: str, *lineno: int) -> None:
        if line == "   Bases: :py:class:`object`":
            return
        super().add_line(line, source, *lineno)

autodoc.ClassDocumenter = MockedClassDocumenter

conf.py中。

相关问题