PEP 287: reStructuredText Standard Docstring Format

[Paul Rubin]

David Goodger <goodger at users.sourceforge.net> writes:
> > The thing I like least about the PEP is that it's written like
> > marketing material
> 
> PEPs *are* marketing tools.  They market proposals to the Python user
> community and PythonLabs, lobbying for support.  They must be
> persuasive, both technically and expositorially.

I hope PEP's are not marketing tools.  Marketing tools are material
written by vendors to get customers to buy products because they are
the vendors products, rather than because they are what the customer
needs.  If a PEP advocates a particular approach over other
approaches, it should come from having carefully compared the
approaches and finding that the PEP's approach is actually the best.
This PEP doesn't give the impression of careful comparison.

> The PEP briefly examines alternatives proposed in the past, on the
> Doc-SIG, in terms of "the generally accepted goals for a docstring
> format".  I think you're reading too much into the prose as it stands.

Since the PEP is being presented to the whole community and not just
to the Doc-SIG (I'd never heard of the Doc-SIG til just now), it
should make its case in detail rather than just giving the conclusion.
That includes the case for having structured doc strings at all--do
you have formatting tools that read these doc strings and produce
printed output like POD?

> This PEP toots its own horn.  Why should it toot somebody else's?

The whole notion of "tooting somebody else's horn" fits the marketing
notion that where a proposal comes from is more important than its
content.  Marketing material typically tries to sell products by
ignoring or obscuring competing products that might actually be
better.  PEP's shouldn't do that, because PEP's aren't marketing
material.  PEP's should examine all the evidence.

> > Finally, among the explicit markup languages examined in the PEP,
> > Texinfo should be included.
> 
> Texinfo is not included because it has never been seriously proposed
> as a docstring format [#]_.  Looking at samples, I can see why.

It seems to have the same advantages as Javadoc and POD, but be more
readable in source form, which is what PEP 287 wanted.

> .. [#] If you care to propose Texinfo as a standard docstring format,
>    please join the Doc-SIG, make your case there, then write a PEP.

I think it should be mentioned in PEP 287, which after all tries to
list all the reasonable alternatives.  

> The entire premise of this PEP and of the Doc-SIG's (at least) 6-year
> docstring markup odyssey is that Pythonistas want a markup that is
> "readable in source form".  We're spoiled by Guido's programming
> language design aesthetics, and that spilled over into the docstring
> markup debate.  Better late than never.

I've written some pretty big Texinfo documents and find Texinfo to be
readable enough in source form, though it looks better after
formatting.  reStructuredText looks pretty simliar to the output of a
Texinfo formatter--maybe Texinfo could be adapted to produce
reStructuredText instead of Info files.