[Doc-SIG] Re: New PEP: reStructuredText Standard Docstring Format
28 Mar 2002 00:06:07 +0100
been away at paid work for a long long time, and it's not going to get
better any time soon unfortunately...
David Goodger <email@example.com> 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
- 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,
.. [#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,