[Doc-SIG] Python docs in reST
Fred L. Drake, Jr.
fdrake at acm.org
Fri May 27 20:38:32 CEST 2005
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 L. Drake, Jr. <fdrake at acm.org>
More information about the Doc-SIG