PEP 287: reStructuredText Standard Docstring Format

[Paul Rubin]

Richard Jones <rjones at ekit-inc.com> writes:
> > 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?

If the proposal is good, the PEP can be written more persuasively
without lengthening it excessively.  

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

OK, that's a start.

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

I guess I don't see plain english markup commands as being more arcane
than remembering what all those funny characters are supposed to mean.