epydoc-devel

[Epydoc-devel] --exclude pattern problem

[<oti...@ya...>]

Dear epydoc devels, since I got a solution for my problem in less than 24
hours, I just thought I may try my luck again :-))
In one of the modules I'm trying to generate the API for, a pretty big 
external module is imported (numpy). I don't want to ship the numpy API
together with my module's API, but excluding "numpy" with the --exclude
switch doesn't help. An example:

foo/
foo/__init__.py

where __init__.py is:
  import numpy as N 
  bar = 1
  __all__ = ['bar','N']

ideally, when I generate the APi with:
epydoc --html --introspect-only --exclude numpy foo/__init__.py
I would like to see only my 'foo' module and my 'bar' variable documented, 
and not the whole numpy tree, which is what happens regardless of the
exclude option. 
What am I doing wrong?

thank you!

tiziano











      ____________________________________________________________________________________
Special deal for Yahoo! users & friends - No Cost. Get a month of Blockbuster Total Access now 
http://tc.deals.yahoo.com/tc/blockbuster/text3.com

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

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

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.  But the generated documentation
won't include any docs for the "N" variable.  (It's not clear to me
what the documentation for that variable should be if it were
included, though, so hopefully that's not a problem.)

If you get a chance to check out the svn revision, please let me know
whether this solves your problem.  For instructions for using svn, see
the eypdoc webpage (http://epydoc.sf.net/).

Thanks,
-Edward

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