Документирование файлов с импортом из x *

Можно ли использовать sphinx .. automodule:: и другие автоматические функции для документирования модулей, содержащих операторы from x import *, без включения всей документации из импортированных модулей?

РЕДАКТИРОВАТЬ: Согласно точке зрения mzjn, если атрибут __module__ импортированных методов не совпадает с именем модуля, они не должны быть задокументированы. Однако для некоторых моих модулей они есть.

мой MLE - это просто файл test_doc.py со следующей строкой:

from pylab import *

и документация:

.. automodule:: agpy.test_doc
    :members:

Если я включу эту строку в test_doc.py:

print "beta.__module__:",beta.__module__

Я получаю ожидаемый результат:

beta.__module__: None

Есть идеи, что происходит? Мог ли я что-то напортачить в conf.py?

РЕДАКТИРОВАТЬ: Обходной путь, согласно ответу mzjn, для изменения атрибута __module__ тех функций, у которых есть __module__==None:

import pylab
from pylab import *
for k,v in pylab.__dict__.iteritems():  
    if hasattr(v,'__module__'):
        if v.__module__ is None:
            locals()[k].__module__ = 'pylab'

python matplotlib python-sphinx
person keflavich    schedule 22.12.2011    source источник
comment
Первый модуль в pylab по алфавиту   -  person keflavich    schedule 26.12.2011

Ответы (1)


arrow_upward
4
arrow_downward

Да, это должно сработать. Из документации:

В директиве automodule с установленным параметромmembers будут документированы только члены модуля, чей атрибут __module__ равен имени модуля, указанному для automodule. Это делается для предотвращения документирования импортированных классов или функций.

Обновлять:

Проблема, похоже, в том, что атрибут __module__ многих членов pylab равен None (члены, определенные в модуле C/Cython mtrand, насколько я могу судить).

Модуль mtrand является частью NumPy. За кулисами pylab.beta (и несколько других функций) является методом класса numpy.random.mtrand.RandomState. Я могу воспроизвести проблему с документацией следующим образом:

С этим источником (pylabtest.py)

from pylab import beta

def mzjn(x):
    """mzjn docstring"""
    return x

и эта исходная документация (pylabtest.rst)

Pylab test
==========

.. automodule:: pylabtest
    :members:

выходные данные Sphinx в pylabtest.html включают как beta, так и mzjn.

Но если

beta.__module__ = "pylab"

добавлен в pylabtest.py, документировано только mzjn.

person mzjn    schedule 24.12.2011
comment
Спасибо... это не сработало, и я не понимаю почему, но я посмотрю, не случилось ли что-то с атрибутами module функций. - person keflavich; 24.12.2011
comment
Спасибо за обновления; жаль, что я пропустил это в течение недели. Я думаю, вы определили проблему, есть идеи, ПОЧЕМУ это происходит? то есть почему функции pylab... без родителей? В любом случае, я принимаю ваш ответ и включаю (довольно уродливый) обходной путь в свой вопрос. - person keflavich; 07.01.2012
comment
Мне также интересно, почему возникает проблема. Странно. pylab.beta имеет атрибут __module__ со значением None. Но у numpy.random.mtrand.RandomState.beta нет даже атрибута __module__. - person mzjn; 07.01.2012