[Python-Dev] Best practice for documentation for std lib

[Eli Bendersky]

On Sun, Sep 22, 2013 at 10:07 AM, Guido van Rossum <guido at python.org> wrote:

> On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull <stephen at xemacs.org>wrote:
>
>> Eli Bendersky writes:
>>
>>  > IMHO the right way to think about it is that the .rst files are by
>>  > far the more important documentation.  Sometimes we forget that
>>  > most Python programmers are people who won't go into the source
>>
>> Why "source"?  The whole point of docstrings is that they are *not*
>> comments found only in the source, but available at run time. In fact,
>> programmers who also use environments like Lisp or R (not to forget
>> Idle) will reach for "help(mean)", and that works fine for Steven,
>> because he provides such nice docstrings.
>>
>> Some people prefer to write separate manuals, and some modules
>> *should* be documented that way because their internal complexity or
>> whatever.  That's true, but I would hope authors who prefer "literate
>> programming" (or the poor man's lit prog that is writing only
>> docstrings) are encouraged to do so when appropriate.
>>
>> Of course, like any other contribution, since that style is *not*
>> currently supported by python-dev, they'd be asked to step up and
>> support it themselves -- if a user reports the docs won't build, they
>> need to address that like they would a build bug in the code.
>
>
> Authors writing 3rd party packages can do what they want.
>
> But for the stdlib it's been settled for ages: docstrings should be
> concise (but not cryptic(*)), longer documentation go into the separately
> written text for docs.python.org.
>

I think there's a general agreement in this thread that we don't intend to
change the status quo. Both .rst docs and docstrings are important. The
remaining question is - can we use some tool to generates parts of the
former from the latter and thus avoid duplication and rot?

Eli
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130922/047b7764/attachment.html>