Thread: [Epydoc-devel] --exclude pattern problem
Brought to you by:
edloper
From: <oti...@ya...> - 2008-03-29 19:00:15
|
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 |
From: Edward L. <ed...@se...> - 2008-03-31 03:23:05
|
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 |
From: Daniele V. <pi...@de...> - 2008-03-31 09:55:39
|
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 |