Sphinx autodoc Django无效

Question

我开始在一个Django项目中使用Sphinx来生成文档，但遇到了一个大问题：

模块的文档是这样写的：

:mod:`models` Module
--------------------

.. automodule:: userprofile.models
    :members:
    :undoc-members:
    :show-inheritance:

相关的代码看起来是这样的：

# models is django.db.models
class ProfileQuerystring(models.Model):
   [..]

问题是，ProfileQuerystring这个类在生成的HTML文档中没有出现。不过，如果我去掉它继承自models.Model的那一行（也就是把那行改成class ProfileQuerystring:），然后重新生成文档，这个类就会被记录下来。

而在那段代码的上面几行，我继承自models.Manager时，这个问题就没有发生。

有没有人能帮我一下，或者给我一点提示？

后续编辑：

如果我手动添加它，它就能正常工作：

.. automodule:: cinely.userprofile.models
    :members:
    :undoc-members:
    :show-inheritance:

.. autoclass:: cinely.userprofile.models.ProfileQuerystring # <-- note this

所以这个类是可以被记录的，但不知为什么automodule就是不愿意。

后续编辑 2：

我尝试去掉Model中的__metaclass__属性，但没有任何变化。而且，由于我开始编辑Django的源代码，我还尝试在控制台打印一些东西，但也没有任何反应。我可以确认我使用的是自定义的Django，因为我已经卸载了用pip安装的版本。

Answer 1

这是一个初步的回答，可能不太准确。因为内容太长，不能放在评论里……不过，如果你看看Django的源代码，就会发现Model和Manager的继承结构是不同的。特别是，Model类使用了__metaclass__这个属性：

Manager:

class Manager(object):
    # Tracks each time a Manager instance is created. Used to retain order.
    creation_counter = 0

Model:

class Model(object):
    __metaclass__ = ModelBase
    _deferred = False

我猜测（但这只是猜测）是当ModelBase创建类的时候，它以某种方式修改了__module__这个属性，这让sphinx（一个文档生成工具）感到困惑，导致它无法理解这个类是属于models模块的。

module = attrs.pop('__module__')
new_class = super_new(cls, name, bases, {'__module__': module})

这个假设和你的观察是一致的：当明确指定要文档化的类时，sphinx在生成文档时没有问题。

这样解释有帮助吗？

---

编辑：我突然想到一个简单的方法来验证这个假设，就是暂时把Model类定义中的__metaclass__那一行注释掉，看看这样sphinx是否能识别它……