[Tutor] How do you use pydoc?

[Brian van den Broek]

Jeff420harris00 at wmconnect.com said unto the world upon 2005-03-14 19:28:
> I have read but don't under stand how to use pydoc. here what i
> read can't figer out how to use it.....
> 

Hi,

try this:

Fire up IDLE and your web browser of choice.

In IDLE's shell, type:

import HTMLParser

There is nothing special about the HTMLParser module other than that 
it is a pure Python module -- I just wanted to pick a concrete case 
for the discussion here.

Now type:

help(HTMLParser)

There. You are now using pydoc :-) It is displaying the documentation 
for the module HTMLParser. Now try typing

help(HTMLParser.HTMLParser)

That's the documentation for one class in the module.

help(HTMLParser.HTMLParser.close)

The documentation for one method of that class.

Now, in the Start Menu entries for Python, find the icon for Module
Docs. Click it, and then click open browser. Scroll down until you see
HTMLParser, and click on it. Your web browser should give you the same 
info as you got from help(HTMLParser), but in a nicer format. That's 
pydoc at work, too.

In IDLE's editor, open HTMLParser.py (mine's at
C:\Python24\Lib\HTMLParser.py).

Now, look at the file HTMLParser.py and compare that to the outputs
that you got above. See if you can see where the help() command got
its output from. The parts of the output that come from text in triple 
quotes are docstrings. Put them in your own modules and functions, and 
you can use help or Module Docs to remind you of what you own code does.

Save a backup copy of HTMLParser.py, and try adding docstrings to
methods like HTMLParser.HTMLParser.handle_comment, and see if you can
see how and why the '#' lines ended up in the help() and Module Docs
output. (Don't forget to save your changes before trying to view them
in your web browser with Module Docs -- and don't forget to restore
the backup when you are done! This is easier to do with Module Docs 
than in the IDLE shell as in the shell pydoc won't know about your 
changes unless you reload the module.)

Best,

Brian vdB