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

[Eli Bendersky]

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

> On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky <eliben at gmail.com> wrote:
>
>>
>> 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?
>>
>
> I don't think that duplication is much of an issue. Natural language
> understanding is not at the level yet where you can generate a meaningful
> summary from a longer text fully automatically (let alone vice versa :-) so
> I think having to write both a concise docstring and a longer more detailed
> description for the Doc tree is not a waste of effort at all.
>

I don't think the proposal is to generate summaries from a longer text.
AFAIU, the proposal is to embed parts of the concise docstring into the
more verbose .rst documentation.

I write .rst docs quite a lot, and as such I do notice the annoying amount
of duplication between docstrings and .rst docs. Without doubt, all the
free-flow text and examples in .rst have to be written manually and are
very important. But for dry method references, it's certainly interesting
to explore the idea of writing them once in the code and then having Sphinx
automatically insert the relevant parts into the .rst before generating
HTML from it. For end users (those who read the docs online) the result is
indistinguishable from what we have now. For us devs it means writing the
same text only once and maintaining it in a single place.

Think about the new statistics module as a guinea pig. Steven will have a
whole lot of copy-pasting to do :-)


>
> As for rot, it's just as likely that rot occurs as a *result* of
> autogeneration. Having to edit/patch the source code in order to improve
> the documentation most likely adds an extra barrier towards improving the
> docs.
>

This is a valid concern, but perhaps one that can be addressed separately?
(i.e. lowering that barrier of entry).

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