[Doc-SIG] Re: New PEP: reStructuredText Standard Docstring Format

[Ueli Schläpfer]

Hi all,

been away at paid work for a long long time, and it's not going to get
better any time soon unfortunately...

David Goodger <goodger@users.sourceforge.net> writes:
[...]

> Paul Moore wrote:
> > I'd suggest that you add a "Benefits" section, explaining the
> > advantages to the individual programmer - *not* to the community as
> > a whole - of the proposal.
> 
> Good idea.  Your list of benefits added.  Any others?

[...]

I haven't been programming Python a whole lot recently, so my
suggestion may be a bit off in the context of a PEP.  

Anyway, I have adopted reST as my tool of choice for producing notes
while doing lab work (mostly in a matlab environment).  Since then,
the quality of such documentation has increased noticeably, mostly for
two reasons:

- I no longer need to switch to another tool, so the threshold has
  fallen to very low.  Note that "another tool" means Winword...
- Still, I have a powerful set of markup constructs at my fingertips
  that let me create the kind of documents I need [#1]_ with more ease
  than any other tool I can think of [#2]_.

Thanks to reST/DPS, I'll soon be able to go ahead and apply the same
tools for extracting documentation out of my python code.  Hey, that's
a printable and a browsable version *for free*!  Personally, I consider
this a large benefit.

BTW, echo from a few colleagues at work that I've exposed to reST has
been very positive so far.  Not sure whether anybody is using it,
though...

Ueli

--------------------------------------------------------------------

.. [#1] Notes interspersed with code snippets, foornotes, maybe
        hyperlinks, and the  occasional screenshot.
.. [#2] My experience so far is that David has done an excellent job
	on the specs as well as on the implementation!  All essential
	constructs for everyday use are there, and much more if
	needed.  If I can think of one exception, it would be
	auto-numbered lists -- I have been thinking of suggesting this
	as a new feature, but I haven't had the time to think through
	whether my candidate syntax ::

	  #. The first item
	  #. And this item was introduced later on.
	  #. Originally the second item.  Glad I didn't have to
	     renumber by hand!

        will work out all right.  Consider the suggestion made,
        then...