Re: [Epydoc-devel] --exclude pattern problem

[Daniele V. <pi...@de...>]

Edward Loper ha scritto:
> On Sat, Mar 29, 2008 at 3:00 PM, oti...@ya...
> <oti...@ya...> wrote:
>>  In one of the modules I'm trying to generate the API for, a pretty big
>>  external module is imported (numpy). [...]
> 
> The problem that trips up epydoc is the combination of these two lines:
> 
>>   import numpy as N
>>   __all__ = ['bar','N']
> 
>>From the __all__ line, epydoc assumes that "foo.N" is part of foo, and
> so it decides it needs to document the value of N.  Of course, the
> value of N is the numpy module, so this goes off and documents numpy.
> 
> I just committed a patch to svn (revision 1810), which modifies the
> docintrospector to treat all module-valued variables as imported, even
> if they appear in __all__.  This will fix the problem of having numpy
> get documented when it shouldn't.  

If I have correctly understood the patch behavior, it prevents to "reshape" a 
package by defining the modules where it is more useful and make it accessible 
where it makes more sense. E.g. in a library:

   my_package/
     __init__.py
     _implementation_details/
       _my_module_unix.py
       _my_module_win32.py

where __init__.py contains:

   all = ['my_module']
   if sys.platform == 'win32':
     import _implementation_details._my_module_win32 as my_module
   else:
     import _implementation_details._my_module_unix as my_module

I think Epydoc should document that you can publicly access 
"my_package.my_module".

In this case I'd prefer the previous behavior: I believe the need to import 
the numpy as N doing "from somewherelse import *" is really something that can 
be done in a different way.

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com