为函数中定义的类生成文档

Question

使用下面的源代码，我想为函数中定义的类 foo 生成文档。

# module named rubbish.py
def factory():
    class foo:
        def bar(self):
            '''bar
            '''
            pass

对应的第一个文件看起来是这样的

rubbish module
==============

.. automodule:: rubbish
    :members:
    :undoc-members:
    :show-inheritance:

并且不会生成类文档。生成的 html 仅显示 factory()。

是否也有任何指令来记录该类？

Answer 1

我设法以一种大概的方式做到了这一点，但它似乎奏效了。

• 我没有“从头开始”测试过这个
• 我正在使用自动文档

代码

my_module.py:

# here lies the class factory
def foo_factory():
  class Foo:
    '''My Foo class is cool'''

    def __init__(self):
      '''Init a Foo 
      Params
      ------
      etc..
      '''
      pass

    def bar(self):
      '''do a bar! 
      Params
      ------
      etc..
      '''
      return 1+1
  
  foo_factory.class_example = Foo # <--Note A.1

将以下内容添加到您的 sphinx conf.py：

def setup(app):
    import my_module
    example = my_module.foo_factory() # <-- Note A.2

    my_module.Foo = my_module.foo_factory.class_example # <--Note A.3
    my_module.Foo.__name__ = 'Foo'# <--Note B.1
    my_module.Foo.__module__ = 'my_module' # <--Note B.2

添加到您的模块 rst 文件（文档类应该出现的位置）：

.. autoclass:: Foo
   :members:

说明

A.1 使类在本地 (foo_factory) 范围之外可访问

A.2 只有在调用工厂后才能访问它，所以我们在这里“虚拟”调用它。

灵感来源：https://stackoverflow.com/a/12039980/4996681

A.3 将类添加为模块的属性

B 完成 A 中的步骤（并将类添加到 rst 文件）后，sphinx 确实将类添加到了文档中，但它显示为“my_module.foo_factory.<locals>.Foo 的别名”。

为了覆盖别名，我们欺骗 sphinx 认为该类是直接在您的模块中的类。

灵感来源：https://stackoverflow.com/a/58982001/4996681