mode (identify the source class for class attrs; segregate attrs according
to source class, and whether class method, static method, property, plain
method, or data; display data attrs; display docstrings for data attrs
when possible).
Alas, this is mondo ugly, and I'm no HTML guy. Part of the problem is
that pydoc's GUI mode has always been ugly under IE, largely because
<small> under IE renders docstrings unreadably small (while sometimes
non-docstring text is painfully large). Another part is that these
segregated listings of attrs would *probably* look much better as bulleted
lists. Alas, when I tried that, the bullets all ended up on lines by
themselves, before the method names; this is apparently because pydoc
(ab?)uses definition lists for format effects, and at least under IE
if a definition list is the first chunk of a list item, it gets rendered
on a line after the <li> bullet.
An HTML wizard would certainly be welcomed here.
This almost entirely replaces how pydoc pumps out class docs, but only
in text mode (like help(whatever) from a Python shell), not in GUI mode.
A class C's attrs are now grouped by the class in which they're defined,
attrs defined by C first, then inherited attrs grouped by alphabetic order
of the defining classes' names.
Within each of those groups, the attrs are subgrouped according to whether
they're plain methods, class methods, static methods, properties, or data.
Note that pydoc never dumped class data attrs before. If a class data
attr is implemented via a data descriptor, the data docstring (if any)
is also displayed (e.g., file.softspace).
Within a subgroup, the attrs are listed alphabetically.
This is a friggin' mess, and there are bound to be glitches. Please
beat on it and complain! Here are three glitches:
1. __new__ gets classifed as 'data', for some reason. This will
have to get fixed in inspect.py, but since the latter is already
looking for any clue that something is a method, pydoc will
almost certainly not know what to do with it when its classification
changes.
2. properties are special-cased to death. Unlike any other kind of
function or method, they don't have a __name__ attr, so none of
pydoc's usual code can deal with them. Worse, the getter and
setter and del'er methods associated with a property don't appear
to be discoverable from Python, so there's really nothing I can
think of to do here beyond just listing their names.
Note that a property can't be given a docstring, either (or at least
I've been unable to sneak one in) -- perhaps the property()
constructor could take an optional doc argument?
3. In a nested-scopes world, pydoc still doesn't know anything about
nesting, so e.g. classes nested in functions are effectively invisible.
inspect.getargspec(obj), test isfunction() directly in pydoc.py instead
of trying to indirectly deduce isfunction() in pydoc by virtue of
failing a combination of other tests. This shouldn't have any visible
effect, except perhaps to squash a TypeError death if there was some path
thru this code that was inferring isfunction() by mistake.
Make synopsis() load modules as '__temp__' so they don't clobber anything.
Change "constants" section to "data" section.
Don't show __builtins__ or __doc__ in "data" section.
For Bob Weiner: don't boldface text in Emacs shells or dumb terminals.
Remove Helper.__repr__ (it really belongs in site.py, and should be guarded by a check for len(inspect.stack) <= 2).
Fix so that docother() doesn't blow up.
Eliminate man() function since doc() and man() did nearly the same thing.
Various other code cleanup and refactoring to reduce duplication.
Simplify and rewrite freshimport() so modules are always up to date,
even within packages (where reload() doesn't work).
Add finalization callback to the server (so that if the server fails to
start for some reason, the main thread isn't left hanging).
Avoid ever using popen on Windows, since it's broken there.
Factor out the business of getting the summary line into splitdoc().
Use the modulename() routine in inspect.
Show all members of modules and classes rather than filtering on leading '_'.
Small typo and formtating fixes.
Don't show warnings when running "pydoc -k".
Font adjustment to improve viewing in Windows (the default monospaced font,
Courier New, seems to have no reasonable size in IE!)
Improve error handling. Try very hard to distinguish between failure to
find a module and failure during the module importing process.
Improve reloading behaviour. (Still needs some work.)
Add '.' to sys.path when running as a script at the command-line.
Don't automatically assume '-g' based on the platform. We'll just have
the batch file supply -g.
Factor description of import errors into DocImportError.__str__.
Add "docother" and "fail" methods to Doc class.
Factor formatting of constants into "docother".
Increase max string repr limit to 100 characters.
Factor page generation into HTMLDoc.page.
Handle aliasing of names (objects appearing under an attribute
name different from their intrinsic __name__) by passing the
attribute name into each doc* method.
Handle methods at top level of modules (e.g. in random).
Try to do reloading efficiently.
Important fixes still to do:
Module reloading is broken by the unfortunate property that
failed imports leave an incomplete module in sys. Still
need to think of a good solution.
Can't document modules in the current directory, due to the
other unfortunate property that sys.path gets '.' when
you run 'python' but it gets the script directory when
you run a script. Need to ponder to find a solution.
The synopsis() routine does not work on .so modules.
Aliases cause duplicate copies of documentation to appear.
This is easy to fix, just more work.
Classes appear as their intrinsic name, not their attribute name,
in the class hierarchy. This should be fixed.
Inherited methods should be listed in class descriptions.
Add checks for .pyo and .pyd.
Collapse docfunction, docmethod, docbuiltin into the one method docroutine.
Small formatting fixes.
Link the segments of a package path in the title.
Link to the source file only if it exists.
Allow modules (e.g. repr.py) to take precedence over built-ins (e.g. repr()).
Add interruptible synopsis scanner (so we can do searches in the background).
Make HTTP server quit.
Add small GUI for controlling the server and launching searches (like -k).
(Tested on Win2k, Win98, and Linux.)
Handle <... at 001B6378> like <... at 0x120f80> (%p is platform-dependent).
Fix RCS version tag handling.
Move __main__ behaviour into a function, pydoc.cli().
Tim Peters
Fred Drake
Ka-Ping Yee
Guido van Rossum