[Python-Dev] PEP 287: reStructuredText Standard Docstring Format

[Jeremy Hylton]

I've never participated in the doc-sig, and I haven't given a lot of
thought to writing complete documentation in docstrings.  Given my
limited interest, I have always been puzzled by why Python has taken
so long to come up with some simple conventions for structuring
docstrings.

The only other example I was familiar with was JavaDoc.  I've never
written an JavaDoc, but I've browsed lots of HTML generated by
JavaDoc.  The one time I looked at JavaDoc, it struck me as quite
simple; I felt confident that I could write it given my limited
knowledge of and interest in HTML.  It also appeared that JavaDoc had
a limited feature set, which also seemed like a strength: Let's not
write fancy, formatted reports in docstrings.

I don't have the same confidence in reStructuredText.  It looks like I
can mostly read it, but it seems hard to learn how to write.  It seems
burdensome to require module authors to learn Python and
reStructuredText just to contribute to the std library.

Jeremy