[Python-Dev] Pydoc Improvements / Rewrite

[Larry Hastings]

Ron Adam wrote:
> Thanks for the link. PEP 287 looks to be fairly general in that it 
> expresses a general desire rather than a specification.
I thought it was pretty specific.  I'd summarize PEP 287 by quoting 
entry #1 from its "goals of this PEP" section:

    * To establish reStructuredText as a standard structured plaintext
      format for docstrings (inline documentation of Python modules and
      packages), PEPs, README-type files and other standalone documents.


Talin wrote:
> Rather than fixing on a standard markup, I would like to see support 
> for a __markup__ module variable which specifies the specific markup 
> language that is used in that module. Doc processors could inspect 
> that variable and then load the appropriate markup translator.
I guess I'll go for the whole-hog +1.0 here.  I was going to say +0.8, 
citing "There should be one---and preferably only one---obvious way to 
do it.".  But I can see organizations desiring something besides ReST, 
like if they already had already invested in their own internal 
standardized markup language and wanted to use that.

This makes the future clear; the default __markup__ in 2.6 would be 
"plain", so that all the existing docstrings work unmodified. At which 
point PEP 287 becomes "write a ReST driver for the new pydoc".  
Continuing my dreaming here, Python 3000 flips the switch so that the 
default __markup__ is "ReST", and the docstrings that ship with Python 
are touched up to match---or set explicitly to "plain" if some strange 
necessity required it.

(And when do you unveil DocLobster?)

Cheers,


/larry/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.python.org/pipermail/python-dev/attachments/20070104/c8e158d3/attachment.html