<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Sun, Sep 22, 2013 at 11:44 AM, Eli Bendersky <span dir="ltr"><<a href="mailto:eliben@gmail.com" target="_blank">eliben@gmail.com</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"><br><div class="gmail_quote"><div class="im">On Sun, Sep 22, 2013 at 11:40 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:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div><div class="gmail_extra"><div class="gmail_quote">On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky <span dir="ltr"><<a href="mailto:eliben@gmail.com" target="_blank">eliben@gmail.com</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 dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote"><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?<span><font color="#888888"></font></span><br>
</div></div></div></div></blockquote></div><br></div></div><div class="gmail_extra">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.<br>
</div></div></blockquote><div><br></div></div><div>I don't think the proposal is to generate summaries from a longer text.</div></div></div></div></blockquote><div><br></div><div>I know, I was being facetious. :-)<br>
</div><div> </div><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 class="gmail_quote"><div>AFAIU, the proposal is to embed parts of the concise docstring into the more verbose .rst documentation.<br>
</div></div></div></div></blockquote><div><br></div><div>I still think that's a bad idea. Someone editing the docstring may introduce a terminology change or some other style/grammar/flow change that makes perfectly sense by itself but doesn't when taken in the context of the larger .rst doc (e.g. it could introducing duplication or cause dissonance between the two parts). Also, someone who wants to improve the docs would have to figure out how to edit the source code if they wanted to change some part of the docs.<br>
</div><div> </div><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 class="gmail_quote"><div>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. <br></div></div></div></div></blockquote><div><br></div><div>You seem to have caught the DRY bug. But it doesn't always make sense to factor things so that everything is said in exactly one place. (For an example of abstraction gone wild, ironically, see docutils and sphinx. I challenge you to find out the actual code that translates e.g. :meth:`foobar` into <a href="(what goes here?)">foobar</a>. :-)<br>
</div><div> </div><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 class="gmail_quote"><div></div><div class="gmail_extra">
Think about the new statistics module as a guinea pig. Steven will have a whole lot of copy-pasting to do :-)<br></div></div></div></div></blockquote><div><br></div><div>The docstrings should probably be limited to the amount of text that's currently devoted to each function in the PEP. What's currently in the docstrings should go into the .rst docs.<br>
</div><div> </div><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 class="gmail_quote"><div>> As for rot, it's just as likely that rot occurs as a *result* of autogeneration. <br>
</div></div></div></div></blockquote><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 class="gmail_quote"><div class="gmail_extra">
> Having to edit/patch the source code in order to improve the <br><div class="gmail_quote"><div class="gmail_extra">> documentation most likely adds an extra barrier towards improving the docs.<br clear="all">
</div><div class="im"><div><br></div></div><div>This is a valid concern, but perhaps one that can be addressed separately? (i.e. lowering that barrier of entry).<span class="HOEnZb"></span><br></div></div></div></div></div>
</div></blockquote></div><br></div><div class="gmail_extra">I can't see that there's any way to interpret the change you propose (changing things so that in order to improve the HTML docs you might need to edit both .rst and .py files) as lowering the barrier to entry. Please give it up.<br clear="all">
</div><div class="gmail_extra"><br>-- <br>--Guido van Rossum (<a href="http://python.org/~guido">python.org/~guido</a>)
</div></div>