狮身人面像 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 创建类时，它以一种混淆 sphinx 的方式操纵 __module__ 属性并使其无法理解该类是模块models的一部分。

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

这个假设与您的观察一致 - 当明确指定要记录的类时 - sphinx 在生成文档时没有问题。

有帮助吗？

---

编辑： 我突然想到，验证这个假设的一种简单方法是临时注释掉 Model 类定义中的 __metaclass__ 行，看看 sphinx 是否采用这种方式起来……