[Python-Dev] Best practice for documentation for std lib

[Georg Brandl]

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