PEP 287: reStructuredText Standard Docstring Format

[Paul Rubin]

Richard Jones <rjones at ekit-inc.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.
> 
> Yeah, I guess at this point it's down to personal preference. I think we can 
> summarise by saying that you're happy to have your documentation source in 
> the texinfo format [#]_, whereas the Structure Text camp would rather see it 
> more looking like actual documentation. Is that fair?

I'm not sure.  The PEP examines a bunch of different markup-based
alternatives rather than comparing markup vs. non-markup.  The problem
it finds with Javadoc source isn't that it's merely non-beautiful, but
that it's actually quite hard to read without practice and HTML
familiarity.  So I don't see it as a matter of a markup vs. a
non-markup camp.  If there were a markup system that was easier to
read directly, that might be a better answer than either Javadoc or
ReST.  I'm pretty comfortable with Texinfo, for example.

I wonder what other systems with inline docs, like Parc Smalltalk or
the MIT Lisp machine, use for syntax?  Emacs Lisp uses plain text with
some typographic conventions, but these don't go as far as ReST, and
it uses a separate system for structured manuals.

> > >    .. contents:: **Table of Contents**
> 
> I think it's justifiable in this case - it saves a lot of typing :)
> 
> Also, the other commonly used explicit markup is images::
> 
>   .. image:: graphic.png
> 
> ... that's pretty hard to do without an explicit markup (short of 
> ASCII-art'ing the PNG :)

You might also want to add a directive for enumerated lists, so that
if you insert a new item in the numbered list in your Roundup docs,
you don't have to manually renumber the rest of them.  And you might
want to add something for multi-column tables (useful for describing
functions and args, for example) so you don't have to draw them as
ascii art.  And so on.  You end up with a hybrid system, which isn't
necessarily so bad, but I don't think it's what you set out to do.

> > 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've started writing a "primer" that should be the first port of
> call. It's a somewhat more verbose version of selected parts of the
> quick reference. Just the basics, explained in a little more
> detailed and human way than the formal documentation. I'd hope that
> that helps a little...

That will help, but I thought the idea of a PEP was to present a complete
specification of the proposed feature, which is why I didn't follow the
external references too carefully.

Btw, could those responding to me please just respond here in the
newsgroup-- I don't need the email carbon copies since I'm reading
here.  Thanks.