我已经开始将 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
。
最佳答案
这是一个初步的答案,可能是错误的。它太长了,无法作为评论......但是,如果你看一下 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 是否以这种方式拾取它...
关于python - 狮身人面像 autodoc django 不工作,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/8593368/