[Python-Dev] Best practice for documentation for std lib
g.brandl at gmx.net
Wed Sep 25 08:30:37 CEST 2013
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
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
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).
More information about the Python-Dev