[Python-Dev] Python Library Reference top page too long (original) (raw)

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:

Front Matter Full Contents

  1. Introduction
  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 "http://docs.python.org/dev/lib/lib.html".

  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 mailing list