Re: [Epydoc-devel] introspection misconception

[Edward L. <ed...@se...>]

>  I'm running into a problem using epydoc with introspection,
>  [...]
>  whereas, using 'introspection-only' I was under the impression that I would
>  get docs for
>   foo, foo.FooBar.
>  [...]
>  What am I missing here? [...]

A couple things: first, if you tell epydoc to document a package
directory, it will automatically document every module in that
package, regardless of whether it gets imported by the main module's
__init__.py file.  If you want to tell epydoc to document *just* the
package itself, and not any of the modules inside the package, you
should run epydoc on the __init__.py file, not on the package
directory.  I.e.:

    % epydoc --introspect-only foo/__init__.py

The second thing is that epydoc is generally careful about figuring
out where something is *actually* defined, and documenting it there;
99% of the time, when an object is imported, it's so that it can be
used, not to move it to a different namespace.  So in this case,
epydoc assumes that FooBar is getting imported into the foo module
just to be used, not to modify the API.  To tell epydoc that you want
FooBar to be listed in the foo module explicitly, you'll need to
define the __all__ variable in the foo module.  In your example case,
you would use:

    __all__ = ['FooBar']

If you make those two changes (defining __all__ in foo/__init__.py,
and running epydoc on foo/__init__.py), then you should get the
results you expect.

One final note, though...  Your package as defined has the following
potentially confusing behavior:

>>> import foo.bar
>>> print foo.bar
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
AttributeError: 'module' object has no attribute 'bar'

Of course, a persistent user can still access the module:

>>> import sys
>>> sys.modules['foo.bar']
<module 'foo.bar' from 'foo/bar.pyc'>

So I'm not sure I see the benefit of deleting 'bar' from the 'foo' namespace.

-Edward