Pythondocs.info : collaborative Python documentation project

[Kay Schluehr]

Brad Allen wrote:
> A.M. Kuchling wrote:
> > However, this code isn't used at the moment because I have no idea
> > what to do about version controlling the links.  Do we just use the
> > current links whenever the HTML is generated?  Make a copy of the list
> > and commit them into SVN, so the links cease to be updated but are
> > consistent for a given version's docs?  It would be nice to figure out
> > what to do.
>
> That sounds like another good reason to handle the examples at
> python.org, but it argues against a wiki approach for examples. Maybe
> the examples should be part of the same SVN repository; if they are
> implemented as doctests they can be validated before each new release.
> On the other hand, that probably only works for very simple examples;
> I've seen some extensive examples at in the Cookbook that might not fit
> well into a doctest.

doctest is not the only way to present examples in code. The other one
is simply a link to the lib/test directory and the approriate
test_<module_name>.py module. Reading testcases is often the only
source I have when I want to understand how something works ( exercise:
try to create a code object from scratch  using the new module and the
desciption provided in the docs ). I find Cookbook recipes a little
over the top for basic use pattern. They are usually not that well
factored that they present a single idea precisely.

Since we are at it: what about two additional directories within the
Python system namely "site-docs" and "site-test" for all kinds of
docs/tests of 3rd party modules/packages? Installing docs using
distutils might automatically update a single HTML site that contains
references to the package docs ( de-installing will cause another
update ).

Python24+-docs
                 +-site-docs
               +-lib
                  +- test
                      +- site-test

or alternatively:

Python24+-lib
                 +-site-packages
                   +- site-docs
                   +- site-test

Executing all testcases of the stdlib already uses reflection over the
modules provided in the directory. Same basic mechanism could be
applied to site-test.

Note that once such an architecture is fixed there is no reason (
besides bandwidth of course ) not to use svn to manage user projects
within site-space completely. I would go even further and suggest to
implement some svn management functions within the Python console such
as:

>>> svn.show_projects()
>>> proj = svn.open_project(project_name)
>>> proj.checkin(module_name)
>>> proj.checkin_all()
>>> svn.checkout(another_project)
etc.