PEP 287: reStructuredText Standard Docstring Format

[Paul Rubin]

"Delaney, Timothy" <tdelaney at avaya.com> writes:
> > That looks pretty similar to an Info file (texinfo output).  I think
> > I'd rather type "@section{Overview}" than have to supply those special
> > underscores directly.
> 
> The whole point is that this is the *input*, optionally to produce another
> format, and is also human-readable in the source code (or any other text
> file). Your statement above simply supports the use of ReST, as its native
> format is "pretty similar" to texinfo output, which you have stated
> previously that you prefer to the texinfo source.

I should be more clear--normally you read Info files through an Info
browser rather than reading the files directly.  They have funny markup
characters in them like ReST does.  My comment can be read as "ReST looks
to me more like object code than source code".

> Huh? If you'd read the accompanying docs, you would know about the ReST
> directives. I wouldn't call the .. contents:: directive "explicit markup"
> considering that it inserts an entire table of contents with one short line

Of course it's explicit markup, regardless of what it does.

> > I looked briefly at the ReST documentation linked from the PEP, but
> > if I'm supposed to read it in detail to be able to use it, I might
> > as well use a more traditional markup language.
> 
> I looked briefly at the Python documentation linked from the web site, but
> if I'm supposed to read it in detail to be able to use it, I might as well
> use a more traditional programming language.

Python is a traditional programming language.