[Doc-SIG] Python docs in reST

[Michael Foord]

Fred L. Drake, Jr. wrote:

>[snip..]
>
> > > Surely implementing a Python source reader (that works by introspection
> > > or whatever) that extracts docstrings and inserts it *into* a reST
> > > document (still a two pass process) would help as a short term measure.
>
>It shouldn't be too hard to implement a specialized URL scheme that converts 
>an object reference to documentation text for some particular system.
>
>
>  
>
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) ?

(or something else altogether ?)

I could knock up the second of these - inserting reST output into a 
document with information about the object referenced. If I can get the 
style right I could even investigate LaTex output (for insertion into 
LaTex documents).

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

Ian's offering produces nice looking output in the page he references - 
but the implementation seems tied to his paste framework.

Best Regards,

Fuzzy
http://www.voidspace.org.uk/python

>  -Fred
>
>  
>