Документирование файлов с помощью "из x import *" - PullRequest
Новая
       6

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

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

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

EDIT: Согласно пункту 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?

EDIT: обходной путь, согласно ответу 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'

1 Ответ

4 голосов
/ 24 декабря 2011

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

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

Обновление:

Кажется, проблема в том, что атрибут __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.

Но если в pylabtest.py добавить 

beta.__module__ = "pylab"

, документируется только mzjn.

...