[Doc-SIG] Python docs in reST

[Fred L. Drake, Jr.]

On Friday 27 May 2005 09:32, Michael Foord wrote:
 > I don't fully follow you Fred - do you mean a URL scheme that *docutils*
 > follows to retrieve the source text, or a URL scheme that another tool
 > recognises and replaces with the text (but still making the original
 > readable) ?

I think that's an implementation detail; it doesn't really matter if it 
inserts nodes in the tree or performs a text replacement as a separate step.

 > I would probably still do this with introspection - although I note the
 > frustration of Mark Williamson trying to use Epydoc to generate docs for
 > Twisted. It can't work for him *because* it uses introspection......

I've used epydoc a bit, but it's hard to use a lot on large projects without a 
general buy-in from the whole team.  Given that it hasn't received any 
maintenance for a long time, it's hard to commit to.

The introspection is an issue in the general case, but extraction via source 
parsing isn't trivial either.  That's why there's always going to be a place 
for manual documentation construction.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>