使用"from x import *"记录文件 [英] Documenting files with "from x import *"

问题描述

sphinx的.. automodule ::和其他自动功能可以用于记录包含 from x import * 语句的模块，而不包含所有来自导入模块的文档吗?

根据 mzjn 的观点，只要导入方法的 __module__ 属性与模块名称不同，就不应该记录它们.但是，对于我的某些模块，它们是.

我的 MLE 只是一个带有以下行的 test_doc.py 文件:

from pylab import *

和文档:

  .. automodule :: agpy.test_doc:成员:

如果我在 test_doc.py 中包含这一行:

print "beta.__module__:",beta.__module__

我得到了预期的结果:

  beta .__ module__:无

知道发生了什么吗?我可以在 conf.py 中搞砸吗?

根据 mzjn 的回答，一种解决方法是更改​​那些具有 __module__==None 的函数的 __module__ 属性:

 导入pylab从 pylab 导入 *对于 pylab.__dict__.iteritems() 中的 k,v:如果hasattr(v，'__ module__'):如果 v.__module__ 是 None:locals()[k].__module__ = 'pylab'

解决方案

是的，应该可以.从文档:

<块引用>

在设置了members选项的automodule指令中，仅记录其 __ module __ 属性等于给automodule的模块名称的模块成员.这是为了防止记录导入的类或函数.

<小时>

更新:

问题似乎是许多pylab成员的__module__属性是None(C/Cython模块中定义的成员<据我所知，是code> mtrand .

mtrand 模块是 NumPy 的一部分.在幕后，pylab.beta(和其他几个函数)是

和此源文档(pylabtest.rst)

  Pylab测试==========.. automodule :: pylabtest:成员:

pylabtest.html 中的 Sphinx 输出包括 beta 和 mzjn.

但是如果

  beta .__ module__ ="pylab"

已添加到pylabtest.py中，仅记录了 mzjn .

Can sphinx's .. automodule:: and other automatic features be used to document modules that include from x import * statements without including all of the documentation from imported modules?

EDIT: As per mzjn's point, as long as the imported methods' __module__ attribute are not the same as the module name, they shouldn't be documented. However, for some of my modules, they are.

my MLE is just a file test_doc.py file with the following line:

from pylab import *

and the documentation:

.. automodule:: agpy.test_doc
    :members:

If I include this line in test_doc.py:

print "beta.__module__:",beta.__module__

I get the expected result:

beta.__module__: None

Any idea what's going on? Could I have screwed something up in conf.py?

EDIT: A workaround, as per mzjn's answer, to change the __module__ attribute of those functions that have __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'

解决方案

Yes, that should work. From the documentation:

In an automodule directive with the members option set, only module members whose __module__ attribute is equal to the module name as given to automodule will be documented. This is to prevent documentation of imported classes or functions.

---

Update:

The problem seems to be that the __module__ attribute of many pylab members is None (the members defined in the C/Cython module mtrand, as far as I can tell).

The mtrand module is part of NumPy. Behind the scenes, pylab.beta (and several other functions) is a method of the class numpy.random.mtrand.RandomState. I can reproduce the documentation issue as follows:

With this source (pylabtest.py)

from pylab import beta

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

and this source documentation (pylabtest.rst)

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

.. automodule:: pylabtest
    :members:

the Sphinx output in pylabtest.html includes both beta and mzjn.

But if

beta.__module__ = "pylab"

is added to pylabtest.py, only mzjn is documented.

这篇关于使用"from x import *"记录文件的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！