重写Sphinx autodoc“别名”以导入私有类？

Question

我有一个Python包，我试图用sphinx-autodoc记录。我的python包有一个__init__.py文件，它从子模块中导出一个类，使其可以在包级别访问。

from a.b.c.d import _Foo as Foo

__all__ = ["Foo"]

如果我这样做，我的（html）文档如下：

  

a.b.c包

     

子模

     

a.b.c.d模块

     

[剪切a.b.c.d模块中不相关公共类的文档]

     

模块内容

     

c模块。

     

A.B.C.的富

     

_Foo

的别名

不是超级有用，因为_Foo（正确）没有文档，因为它是a.b.c.d子模块中的私有类。

我可以将以下内容添加到conf.py中，以确保记录模块中的私有类定义。

def skip(app, what, name, obj, skip, options):
    if name == "_Foo":
        return False
    return skip

其他替代方案，但不是我尝试过的好东西：

1. 将a.b.c.d._Foo重命名为a.b.c.d.Foo（然后将导入更新为from a.b.c.d import Foo） - 然后我将该类记录两次，一次在 abcd模块下标题，再次在模块内容标题下。
2. 将a.b.c.d.Foo重命名为a.b.c.d.MyFoo，然后导入（from a.b.c.d import MyFoo as Foo）会导致MyFoo被记录，Foo被列为{{1}的别名}}。

理想情况下，我希望私有定义保持未记录状态，但要将导入到包中的版本完整记录下来。有谁知道我怎么做到这一点？

Answer 1

Sphinx使用类的__name__和__module__以及类所有者的__module__成员来确定它是别名还是真实对象。通过显式设置这些成员，可以欺骗Sphinx认为您的导入类是真正的类。

from a.b.c.d import _Foo as Foo
Foo.__module__ = __name__
Foo.__name__ = 'Foo'

Answer 2

使用members指令，可以显示除以'_'开头的成员以外的所有成员。您可以将_Foo保留在a.b.c.d中，而将其记录为Foo在a.b.c中。我会将_Foo导入为from a.b.c.d import _Foo，然后添加任何类似的文档：

Foo = _Foo
''' blah blah blah '''

如果由于某种原因，您不想在a.b.c的命名空间中使用_Foo，那么您也可以这样做：

from a.b.c.d import _Foo as Foo
Foo = Foo
''' blah blah blah '''