如何使用 Sphinx autodoc 记录嵌套类？答案

【问题标题】：How to document nested classes with Sphinx's autodoc?如何使用 Sphinx autodoc 记录嵌套类？
【发布时间】：2015-02-04 21:37:11
【问题描述】：

有没有办法用 Sphinx 的 autodoc 插件记录嵌套类？

在：

class A:
    class B:
    """
    class B's documentation.
    """

    # ...

我想在我的.rst 文件中使用autoclass 或类似的东西来专门记录A.B。

我试过了：

.. currentmodule:: package.module

.. autoclass:: A.B

和

.. autoclass:: package.module.A.B

没有成功：

/path/to/file.rst:280: WARNING: autodoc: failed to import class 'B' from module 'package.module.A'; the following exception was raised:

...

Traceback (most recent call last):
  File "/usr/lib/python3.4/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
    __import__(self.modname)
ImportError: No module named 'package.module.A'; 'package.module' is not a package

当然A 不是模块；似乎 autoclass 正在考虑将最后一个 . 之前的任何东西作为包和模块。

【问题讨论】：

这不是关于如何让 Sphinx 做你想做的事的答案，但是嵌套类在 Python 中非常少见，所以你可能会继续发现对它们的不良支持。你可以让你的类取消嵌套，让 Sphinx 非常容易地工作。
是的，我知道。不幸的是，这些嵌套类是现有 API 的一部分。下一个主要版本应该取消嵌套它们，但与此同时，我仍然需要记录它们。
我创建了一个狮身人面像bug report。
我们一直使用嵌套类，以保持全局命名空间尽可能干净并传达上下文。

标签： python python-3.x python-sphinx inner-classes autodoc

【解决方案1】：

试试：

.. autoclass:: package.module::A.B

来源：https://groups.google.com/forum/#!topic/sphinx-users/IL5V7HR1ZYE

【讨论】：