Sphinx自动文档生成工具在Django中无法正常工作

Question

我已经开始在一个Django项目中使用Sphinx，但是我遇到了一个难题：模块的文档是这样的：

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

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

相关代码如下所示：

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

问题在于HTML构建中没有出现ProfileQuerystring。但是，如果我删除对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安装的版本。

- Gabi Purcaru

---

好问题（+1）...我没有答案，但我会尝试玩一下autodoc defaults。它们可能不是问题所在，但是这是我首先想到的东西... :( - mac

不确定这个是否有帮助，想至少发布链接。 - mac

@mac，感谢您的帮助，但不幸的是我无法修复它。 - Gabi Purcaru

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

模型：

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是否能够识别出来...

- mac

---

谢谢你的帮助；不幸的是它不起作用（请看我的编辑） - Gabi Purcaru

@GabiPurcaru - 你能发布（或链接到）一个我们可以尝试的sscce吗？这是一个迷人的难题，值得一试！ :) - mac

非常抱歉没有及时回答你的问题；我已尝试过，但无法找到问题所在（当我在一个干净的Django项目上尝试时，它可以工作）。鉴于这种情况，我会接受您的答案，因为您帮助了我很多。谢谢！ - Gabi Purcaru