python - 狮身人面像 autodoc django 不工作

Question

我已经开始将 Sphinx 用于 django 项目，但遇到了障碍:

模块的文档是这样的:

: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 和使其无法理解该类是模块 models 的一部分。

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

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

有帮助吗？

---

编辑: 我刚刚想到，验证这个假设的一个简单方法是临时注释掉 Model 中的 __metaclass__ 行类定义并查​​看 sphinx 是否以这种方式拾取它...