[Python-Dev] Python Library Reference top page too long
Edward C. Jones
edcjones at comcast.net
Thu Mar 16 18:53:55 CET 2006
The contents page for the Python Library Reference
("http://docs.python.org/dev/lib/lib.html") has become much too long. I
suggest that it should be designed like the top page for portal web
sites. For example see "http://www.dmoz.org/". I suggest that "lib.html"
be replaced by "lib_index.html" and "lib_contents.html". The latter is
the current "lib.html". "lib_index.html" should look something like:
2. Built-in Objects
functions, types, exceptions, constants
3. File and Directory Access
open, file objects, os, os.path, ...
4. Generic Operating System Services
os, time, optparse, ...
5. Python Runtime Services
sys, __main__, __future__, ...
6. String Services
type str, string, re, ...
7. Numeric and Mathematical Modules
math, random, decimal, ...
Both "lib_index.html" and "lib_contents.html" should be accessible from
the top Python Documentation page.
Here are two principles I feel would be useful to follow. References are
to the Python 2.5 documentation at
1. Important, commonly used, or confusing modules should be near the
top. The things I look up the most are os.path, os (files and
directories), and string attributes. "sys" should also be near the top
because of "sys.argv", "sys.stderr", and "sys.exit". Etc, etc.
2. Put cross-links everywhere. For example the documentation for built
in function "file" has a link to "File Objects". There should also be a
link to "open()" and to sections 13.1.2, 13.1.3, 13.1.4, and chapter 10.
(What became of the often proposed and long overdue reorganization of "os"?)
More information about the Python-Dev