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.
--
http://mail.python.org/mailman/listinfo/python-list
