Сфинкс Autodoc Django не работает - PullRequest
Новая
       14

Сфинкс Autodoc Django не работает

3 голосов
/ 21 декабря 2011

Я начал использовать 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 :

Я пытался удалить атрибут __metaclass__ из Model, но ничего не происходит. Кроме того, поскольку я начал редактировать исходный код Django, я воспользовался возможностью напечатать что-нибудь на консоль, но ничего не произошло. Я могу подтвердить, что используется настроенный django, потому что я удалил установленный pip.

1 Ответ

1 голос
/ 22 декабря 2011

Это предварительный ответ, и он может быть неправильным. Это было просто слишком долго, чтобы поместить в качестве комментария ... Однако, если вы посмотрите на источник django, вы заметите, что Model и Manager имеют различное наследование три. В частности, Модель класса использует атрибут __metaclass__:

Менеджер 

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__ таким образом, что вводит в заблуждение сфинкса и делает невозможным для него понять, что класс часть модуля models. 

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

Эта гипотеза согласуется с вашим наблюдением о том, что - когда класс для документа указан явно - у sphinx нет проблем с генерацией документации.

Помогает ли?

РЕДАКТИРОВАТЬ: Мне только что пришло в голову, что простой способ проверить эту гипотезу состоит в том, чтобы временно закомментировать строку __metaclass__ в определении класса Model и посмотреть, подхватит ли ее сфинкс ...

...