PEP 287: reStructuredText Standard Docstring Format

[Richard Jones]

On Wed, 3 Apr 2002 16:34, Paul Rubin wrote:
> 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.

Wow, that's a very narrow definition of marketing. I know people who are in 
martketing, and they'd go green hearing such a definition :)

I believe you are confusing marketing with advertising.


>  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.

It points to the documents that David and others have written that do. Did 
you read those? Ooh. Dejavu. I've said that before, I swear...

> David Goodger wrote:
> > 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.

The PEP is already very long. Did you want David to include _all_ the 
documentation from the ReST website in the PEP to back it up?


> 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?

I believe the docstring extraction is performed by pydoc and is a little 
manual at the moment, but the upshot is yes, he does (printing of HTML is 
valid at this early stage of development).


> 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.

But the whole point of this is that the _source_ of the documentation is the 
reStructuredText-formatted text, not some other more arcane format that must 
be processed to produce reStructuredText files.


    Richard