[Twisted-Python] Re: Weekly Bug Summary

[Michael Hudson]

glyph at divmod.com writes:

> 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>'

Ah, right.

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

pydoctor also optionally generates a system pickle with all the
information in, so you shouldn't really even need to parse anything...

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

I would also like a pony :)

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

pydoctor depends on nevow (practically speaking, anyway; there's a
writer that just builds up HTML by string interpolation but all the
funky new stuff is just in the nevow writer).  It is also vaguely
designed to be used as a library, so I think lore could import it.

Cheers,
mwh

-- 
  Also, remember to put the galaxy back when you've finished, or an
  angry mob of astronomers will come round and kneecap you with a
  small telescope for littering. 
       -- Simon Tatham, ucam.chat, from Owen Dunn's review of the year