Sphinx autodoc django无法正常工作

Question

I've started using Sphinx for a django project, and I've hit a brick wall:

The modules are documented with something like this:

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

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

The relevant code looks like this:

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

The problem is that ProfileQuerystring does not appear in the HTML build. If, however, I remove the inheritance to models.Model (so the line looks like class ProfileQuerystring: ) and re-build, the class gets documented.

This doesn't happen a few lines above that code, where I inherit from models.Manager .

Can anyone help me out or at least give me a hint?

LATER EDIT :

If I manually add it, it works:

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

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

So the class can be documented, but somehow automodule doesn't want to.

LATER EDIT 2 :

I've tried removing the __metaclass__ attribute from Model , but nothing happens. Also, since I've started editing the Django source, I took the chance to print something to the console, but nothing happened. I can confirm that the customized django is used, because I've uninstalled the pip installed one.

Answer 1

This is a tentative answer, and it might be wrong. It was simply too long to be put as a comment... However, if you take a look at the django source you will notice that Model and Manager have a different inheritance three. In particular, the Model class uses the __metaclass__ attribute:

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

My guess (but it's nothing more than that: a guess) is that when ModelBase creates the class, it manipulate the __module__ attribute in a way that confuses sphinx and makes impossible for it to understand that the class is part of the module models .

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

This hypothesis is consistent with your observation that - when the class to document is specified explicitly - sphinx has no problem in generating the documentation.

Does it help?

---

EDIT: Just occurred to me that a simple way to verify this hypothesis would be to temporary comment out the __metaclass__ line in the Model class definition and see if this way sphinx picks it up...