<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Sun, Sep 22, 2013 at 10:07 AM, Guido van Rossum <span dir="ltr"><<a href="mailto:guido@python.org" target="_blank">guido@python.org</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div><div class="h5"><div class="gmail_quote">On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull <span dir="ltr"><<a href="mailto:stephen@xemacs.org" target="_blank">stephen@xemacs.org</a>></span> wrote:<br>



<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div>Eli Bendersky writes:<br>
<br>
 > IMHO the right way to think about it is that the .rst files are by<br>
 > far the more important documentation.  Sometimes we forget that<br>
 > most Python programmers are people who won't go into the source<br>
<br>
</div>Why "source"?  The whole point of docstrings is that they are *not*<br>
comments found only in the source, but available at run time. In fact,<br>
programmers who also use environments like Lisp or R (not to forget<br>
Idle) will reach for "help(mean)", and that works fine for Steven,<br>
because he provides such nice docstrings.<br>
<br>
Some people prefer to write separate manuals, and some modules<br>
*should* be documented that way because their internal complexity or<br>
whatever.  That's true, but I would hope authors who prefer "literate<br>
programming" (or the poor man's lit prog that is writing only<br>
docstrings) are encouraged to do so when appropriate.<br>
<br>
Of course, like any other contribution, since that style is *not*<br>
currently supported by python-dev, they'd be asked to step up and<br>
support it themselves -- if a user reports the docs won't build, they<br>
need to address that like they would a build bug in the code.</blockquote><div> </div></div></div></div>Authors writing 3rd party packages can do what they want.<br><br></div><div class="gmail_extra">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 <a href="http://docs.python.org" target="_blank">docs.python.org</a>.</div>

</div></blockquote><div><br></div><div>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?<br>

<br></div><div>Eli<br></div><div> <br></div></div></div></div>