Am 23.09.2013 00:03, schrieb Guido van Rossum: > AFAIU, the proposal is to embed parts of the concise docstring into the > more > verbose .rst documentation. > > > 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).
Yes, this style is better suited for smaller documentations where there isn't that much more info in the .rst than in the docstring -- the .rst giving maybe an introduction and then just a logical order in which docstrings are pulled. Since we have the policy (now reconfirmed) of small docstrings and more verbose prose on docs.python.org, this would not be feasible there. > 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. I agree that is another good point. And should the "suggest a change on docs.python.org" feature ever be shipped, it will be much harder, if not impossible, to generate a patch and let developers submit it automatically. > 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. > > > 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>. :-) PSA: I can only recommend to everyone not to take up Guido's dare... (and I'm not terribly proud of that). cheers, Georg _______________________________________________ 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
