On Sun, Sep 22, 2013 at 10:07 AM, Guido van Rossum <gu...@python.org> wrote:
> On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull > <step...@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
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
