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:
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,
* 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: 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/