[Python-Dev] New Pythondoc by effbot

[Brett Cannon]

> [Fredrik, later]
> > if we move over to a web-oriented (wiki-ish) maintenance model, we
> > probably have to accept that "X" will, sometimes, be a future release.
>
> This makes me worry that you're thinking of abandoning having separate
> docs per version. That would be a shame; I think the docs ought to be
> maintained well enough to be authorative for a particular version
> (modulo bugs in the docs). Perhaps we could add links that let you
> navigate between versions quickly, and hopefully we can somehow
> (optionally?) merge the wiki-style user comments across versions.
> (Although I can also see the point of starting afresh for each release
> -- at some point the sheer amount of (possibly outdated) user comments
> reduces their usefulness.

It would probably be best to clear out the comments for each minor
release.  Otherwise they will just organically grow.

Problem is that useful examples might disappear.  This might suggest
that having possible example usage tagged on to a method or such could
be saved and, by default, made folded (ala folding in Ian Bicking's
Python doc comment system:
http://blog.ianbicking.org/python-doc-comments.html).  These examples
could also be verified using something like doctest so that
invalidated examples do not persist or submitted.

And to /F, kudos from me.  I have been randomly thinking about it and
I understand your desire for semantic markup now.  Hopefully something
can get hammered out so that at least the Python 3 docs can premiere
having been developed on by the whole community.

-Brett