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/
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
