Thread: [Epydoc-devel] Re: epydoc questions
Brought to you by:
edloper
Menu
▾
▴
epydoc-devel
|
From: Robin D. <ro...@al...> - 2004-04-23 21:01:41
|
Edward Loper wrote: > Robin Dunn wrote: > [...] >> * Using the new wx package several of the core submodules are imported >> into the package namespace so the programmer doesn't have to worry >> about explicitly importing those submodules. For example, instead of >> using wx.core.Window the programmer will just use wx.Window. Is there >> any trick you can think of to make epydoc document the objects in >> those submodules as if they were actually in wx itself? That way the >> reader of the docs still won't have to know anything about the >> implementation details and the docs will accurately reflect how it is >> supposed to be used. > > > This would be hard to do with the current system. But it should become > easier after I make some of the architectural changes I mentioned. Hi Edward, Is there anything written about this new architecture that I could review? Is there an ETA? And if I decide that I am insane enough <wink!> to try and implement the above feature on the current system do you have any suggestions for how to go about doing it? -- Robin Dunn Software Craftsman http://wxPython.org Java give you jitters? Relax with wxPython! |
|
From: Edward L. <ed...@gr...> - 2004-04-23 21:35:00
|
>> This would be hard to do with the current system. But it should
>> become easier after I make some of the architectural changes I mentioned.
>
> Is there anything written about this new architecture that I could
> review?
It's pretty preliminary right now. Once I get a little further along,
I'll write up a description/explanation, but right now I'm trying to
figure out exactly how I want it to look. Some of the motivations
behind it are...
- better support for extracting docs via source code parsing
- plug-in support for extending epydoc (eg there will be a zope
plug-in that handles zope interfaces, etc.)
- more consistent & flexible handling of object names.
At some point, I should write up a description & an an explination of
what's motivating it, but I haven't had a chance yet. I just checked
some of my preliminary work in to cvs:
epydoc/sandbox/epydoc3/epydoc/*
But at this point, it doesn't do much.
> Is there an ETA?
At least a month, maybe more. (I don't get as much time to work on
epydoc as I'd like).
> And if I decide that I am insane enough
> <wink!> to try and implement the above feature on the current system do
> you have any suggestions for how to go about doing it?
So basically you want some of the imported objects (eg wx.core.Window)
to be treated as if they were defined locally. But I'm sure you don't
want *all* imported objects to be listed as if they're defined locally.
So epydoc needs some information source to decide which imported objects
it should pretend are defined locally.
One option is to use __all__. In particular, any imported objects
listed in __all__ will be treated as if they were defined locally.
Another option is to define a new field for the module docstring, that
declares that an object should be treated as if it was defined locally.
Something like "@local: Window", although I'm not crazy about that name.
In either case, you would modify ModuleDoc.__init__ and
ModuleDoc._find_imported_variables, to treat the desired values as
non-imported (i.e., add them to self._x instead of self._imported_x).
-Edward
|
|
From: Robin D. <ro...@al...> - 2004-04-24 00:29:13
|
Edward Loper wrote: > >> And if I decide that I am insane enough <wink!> to try and implement >> the above feature on the current system do you have any suggestions >> for how to go about doing it? > > > So basically you want some of the imported objects (eg wx.core.Window) > to be treated as if they were defined locally. Yes. > But I'm sure you don't > want *all* imported objects to be listed as if they're defined locally. Actually, in this case I do want all of them. The wx.core and a few other modules are really just implementation details that are required because some C/C++ compilers start to choke when compiling files more than about 60K lines of code, and because SWIG can't split a single extension module across multiple C files. For the docs my preference would be that "core" and "wx.core" does not show up anywhere, and that everything that lives in wx.core would just be documented as "wx.Whatever". > > So epydoc needs some information source to decide which imported objects > it should pretend are defined locally. > > One option is to use __all__. In particular, any imported objects > listed in __all__ will be treated as if they were defined locally. With hundreds of objects per module that gets to be a little difficult to maintain... I'll keep it in mind though. > > Another option is to define a new field for the module docstring, that > declares that an object should be treated as if it was defined locally. > Something like "@local: Window", although I'm not crazy about that name. This too. > > In either case, you would modify ModuleDoc.__init__ and > ModuleDoc._find_imported_variables, to treat the desired values as > non-imported (i.e., add them to self._x instead of self._imported_x). Yep, I discovered that bit in the code shortly after sending the prior message, and I have been experimenting a bit since then. Nothing is really working yet, but at least I'm getting very familiar with the code ;-) -- Robin Dunn Software Craftsman http://wxPython.org Java give you jitters? Relax with wxPython! |
|
From: Edward L. <ed...@gr...> - 2004-04-24 03:16:26
|
Robin Dunn wrote:
>> But I'm sure you don't want *all* imported objects to be listed as if
>> they're defined locally.
>
> Actually, in this case I do want all of them.
For this one module, maybe, but not in general, right? So maybe what
you want is a module-level way of saying "treat imported objects as
locally defined" instead of an object-level one?
> For the docs my preference would be that "core" and "wx.core" does not
> show up anywhere, and that everything that lives in wx.core would just
> be documented as "wx.Whatever".
If "core" isn't listed in wx.__all__, then it will be treated as
"private." Combined with treaing all names in __all__ as locally
defined, this might do what you want. Alternatively, you might consider
renaming wx.core to wx._core (which will make it very clear to your
users that it's an implementation module, and shouldnt be used directly).
>> So epydoc needs some information source to decide which imported
>> objects it should pretend are defined locally.
>>
>> One option is to use __all__. In particular, any imported objects
>> listed in __all__ will be treated as if they were defined locally.
>
> With hundreds of objects per module that gets to be a little difficult
> to maintain... I'll keep it in mind though.
There's no reason that __all__ has to be defined using a list literal.
In particular, you might consider doing something like this:
# Import all objects from wx.core (the implementation module)
from wx.core import *
# Declare that all of the objects imported from wx.core are public
import wx.core
__all__ += [name for name in dir(wx.core)
if not name.startswith('__') and name.endswith('__')]
del wx.core
>> Another option is to define a new field for the module docstring, that
>> declares that an object should be treated as if it was defined
>> locally. Something like "@local: Window", although I'm not crazy
>> about that name.
>
> This too.
@local would presumably support the "*" syntax that's supported by
@group, @sort, and @undefined. In particular, you could just do:
@local: *
I think I like the __all__ solution better, though.
-Edward
|
|
From: Robin D. <ro...@al...> - 2004-04-24 16:53:09
|
Edward Loper wrote: > Robin Dunn wrote: > >>> But I'm sure you don't want *all* imported objects to be listed as if >>> they're defined locally. >> >> >> Actually, in this case I do want all of them. > > > For this one module, maybe, but not in general, right? So maybe what > you want is a module-level way of saying "treat imported objects as > locally defined" instead of an object-level one? > >> For the docs my preference would be that "core" and "wx.core" does not >> show up anywhere, and that everything that lives in wx.core would just >> be documented as "wx.Whatever". > > > If "core" isn't listed in wx.__all__, then it will be treated as > "private." Combined with treaing all names in __all__ as locally > defined, this might do what you want. Alternatively, you might consider > renaming wx.core to wx._core (which will make it very clear to your > users that it's an implementation module, and shouldnt be used directly). Ah, thanks, it makes sense now. For some reason a couple synapses were not making the connection before. Now I know how some of my users feel when I point out the obvious to them! ;-) -- Robin Dunn Software Craftsman http://wxPython.org Java give you jitters? Relax with wxPython! |
|
From: Robin D. <ro...@al...> - 2004-04-26 22:46:40
|
Robin Dunn wrote: > Edward Loper wrote: > >> Robin Dunn wrote: >> >>>> But I'm sure you don't want *all* imported objects to be listed as >>>> if they're defined locally. >>> >>> >>> >>> Actually, in this case I do want all of them. >> >> >> >> For this one module, maybe, but not in general, right? So maybe what >> you want is a module-level way of saying "treat imported objects as >> locally defined" instead of an object-level one? >> >>> For the docs my preference would be that "core" and "wx.core" does >>> not show up anywhere, and that everything that lives in wx.core would >>> just be documented as "wx.Whatever". >> >> >> >> If "core" isn't listed in wx.__all__, then it will be treated as >> "private." Combined with treaing all names in __all__ as locally >> defined, this might do what you want. Alternatively, you might >> consider renaming wx.core to wx._core (which will make it very clear >> to your users that it's an implementation module, and shouldnt be used >> directly). > > > > Ah, thanks, it makes sense now. For some reason a couple synapses were > not making the connection before. Now I know how some of my users feel > when I point out the obvious to them! ;-) > In case anybody else is reading this besides Edward and myself, I've just attached a patch for implementing this to the RFE: http://sourceforge.net/tracker/index.php?func=detail&aid=938924&group_id=32455&atid=405621 Works great on wxPython and didn't seem to cause any problems on the other tests I threw at it. -- Robin Dunn Software Craftsman http://wxPython.org Java give you jitters? Relax with wxPython! |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X