Question

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'

Answer 1

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.