[Twisted-Python] Re: Weekly Bug Summary

[James Y Knight]

On Apr 17, 2006, at 7:40 PM, glyph at divmod.com wrote:

>
>
> On Mon, 17 Apr 2006 15:30:22 +0100, Michael Hudson <mwh at python.net>  
> wrote:
>> glyph at divmod.com writes:
>>>> Does this bother you somehow?
>>>
>>> Nope.  Just seems like yet another indication that it should really
>>> be lore --api ;-) Or rather, lore, like trial, should be able to
>>> take a file (HTML or Python) or module name.
>>
>> It doesn't and can't really work like that though, pydoctor really
>> needs to work on a whole system/package at a time.
>
> Absolutely - you are suggesting that the parity is even greater  
> than I am.  'trial twisted' ~= 'lore twisted'.  Or perhaps 'lore  
> zope.interface twisted <something that means the stdlib too>'
>
> One really nice thing that lore could do is look for API references  
> in "howto" documentation (man, that stuff needs a better name) and  
> generate the API documentation concurrently so that it can print  
> warnings if such APIs don't exist.  Of course, by no means  
> impossible if they were separate projects.  Pydoctor generates  
> actually parseable output, as opposed to the crap soup of HTML that  
> comes out of epydoc.
>
> Still, it would be super nice if there could be a single,  
> integrated step for building the whole book in HTML and PDF form,  
> then packaging the API docs into an indexed, annotated appendix,  
> included within the LaTeX document, for example.  That sort of  
> thing seems like it'd be hard to pull off without the code being  
> closely related, however, I guess lore could always just import  
> pydoctor (assuming no pydoctor=>twisted dependency).

It seems to me that pydoctor should remain separate -- I suspect it  
would be more useful for other projects if it was not integrated with  
lore.

James