Learning Python - Mark Lutz [217]
| dict(mapping) -> new dictionary initialized from a mapping object's
...more omitted...
>>> help(str.replace)
Help on method_descriptor:
replace(...)
S.replace (old, new[, count]) -> str
Return a copy of S with all occurrences of substring
...more omitted...
>>> help(ord)
Help on built-in function ord in module builtins:
ord(...)
ord(c) -> integer
Return the integer ordinal of a one-character string.
Finally, the help function works just as well on your modules as it does on built-ins. Here it is reporting on the docstrings.py file we coded earlier. Again, some of this is docstrings, and some is information automatically extracted by inspecting objects’ structures:
>>> import docstrings
>>> help(docstrings.square)
Help on function square in module docstrings:
square(x)
function documentation
can we have your liver then?
>>> help(docstrings.Employee)
Help on class Employee in module docstrings:
class Employee(builtins.object)
| class documentation
|
| Data descriptors defined here:
...more omitted...
>>> help(docstrings)
Help on module docstrings:
NAME
docstrings
FILE
c:\misc\docstrings.py
DESCRIPTION
Module documentation
Words Go Here
CLASSES
builtins.object
Employee
class Employee(builtins.object)
| class documentation
|
| Data descriptors defined here:
...more omitted...
FUNCTIONS
square(x)
function documentation
can we have your liver then?
DATA
spam = 40
PyDoc: HTML Reports
The help function is nice for grabbing documentation when working interactively. For a more grandiose display, however, PyDoc also provides a GUI interface (a simple but portable Python/tkinter script) and can render its report in HTML page format, viewable in any web browser. In this mode, PyDoc can run locally or as a remote server in client/server mode; reports contain automatically created hyperlinks that allow you to click your way through the documentation of related components in your application.
To start PyDoc in this mode, you generally first launch the search engine GUI captured in Figure 15-1. You can start this either by selecting the “Module Docs” item in Python’s Start button menu on Windows, or by launching the pydoc.py script in Python’s standard library directory: Lib on Windows (run pydoc.py with a -g command-line argument). Enter the name of a module you’re interested in, and press the Enter key; PyDoc will march down your module import search path (sys.path) looking for references to the requested module.
Figure 15-1. The Pydoc top-level search engine GUI: type the name of a module you want documentation for, press Enter, select the module, and then press “go to selected” (or omit the module name and press “open browser” to see all available modules).
Once you’ve found a promising entry, select it and click “go to selected.” PyDoc will spawn a web browser on your machine to display the report rendered in HTML format. Figure 15-2 shows the information PyDoc displays for the built-in glob module.
Figure 15-2. When you find a module in the Figure 15-1 GUI (such as this built-in standard library module) and press “go to selected,” the module’s documentation is rendered in HTML and displayed in a web browser window like this one.
Notice the hyperlinks in the Modules section of this page—you can click these to jump to the PyDoc pages for related (imported) modules. For larger pages, PyDoc also generates hyperlinks to sections within the page.
Like the help function interface, the GUI interface works on user-defined modules as well as built-ins. Figure 15-3 shows the page generated for our docstrings.py module file.
Figure 15-3. PyDoc can serve up documentation pages for both built-in and user-coded modules. Here is the page for a user-defined module, showing all its documentation strings (docstrings) extracted from the source file.
PyDoc can be customized and launched in various ways we won’t cover here; see its entry in Python’s standard library manual for more details. The main thing to take away from this section