[Python-Dev] Pydoc Improvements / Rewrite
Larry Hastings
larry at hastings.org
Fri Jan 5 07:44:16 CET 2007
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
More information about the Python-Dev
mailing list