[Twisted-Python] Re: Weekly Bug Summary

[glyph at divmod.com]

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).