Kent Johnson said unto the world upon 2005-04-17 16:17:
Brian van den Broek wrote:
Kent Johnson said unto the world upon 2005-04-16 16:41:
Brian van den Broek wrote:
I've just spent a frustrating bit of time figuring out why pydoc didn't extract a description from my module docstrings. Even though I had a well formed docstring (one line, followed by a blank line, followed by the rest of the docstring), when I ran Module docs, my modules showed up as having "no description". ("Module docs" referring to the shortcut installed on Windows that launches the pydoc server.)
I'm not sure what you mean by "the results list in the TKinter interface to the pydoc server". I ran the server, clicked "open browser" and browsed to a module in site-packages; that worked fine for me under Win2K and Python 2.4.1.
By "the TKinter interface to the pydoc server" I mean the window that pops up when you select the Module Docs shortcut. It is pictured here <http://www.onlamp.com/python/2001/04/18/graphics/pydoc1.gif>, which is Fig.1 in an article on pydoc by Cameron Laird <http://www.onlamp.com/pub/a/python/2001/04/18/pydoc.html>. By "results list" I mean the gray-backround'ed box immediately below the "Search for" input box in the illustration.
The puzzle for me was that if I enter my module name in the "Search for" box, it shows up in the list of results, as expected. But whether the results list entry for my module incorporates the description form my module's docstring or instead shows my module as having "(no description)" is a function of which style of triple quotes I used. (If my module docstring is enclosed by triple double quotes, the description is extracted from my module's docstring. If it uses triple single quotes instead, for purposes of the results list my module's docstring is ignored, and the module is listed as having "(no description)".)
OK, now I get it. I don't use pydoc much and I missed that display.
This is indeed a bug in pydoc. If you look at lines 194, 195 and 201 in pydoc.py (Python 2.4.1 version) you can see that it is parsing out the module docstring itself and it only looks for """ strings.
Here is a patch that accepts ''' strings as well. Though a better patch would allow any kind of string. I filed a bug report at
http://sourceforge.net/tracker/index.php?func=detail&aid=1185124&group_id=5470&atid=105470
Kent
194,195c194,195
< if line[:4] == 'r"""': line = line[1:]
< if line[:3] == '"""':
---
> if line[:4] == 'r"""' or line[:4] == "r'''": line = line[1:]
> if line[:3] == '"""' or line[:3] == "'''":
201c201
< result = strip(split(line, '"""')[0])
---
> result = strip(re.split('\'\'\'|"""', line)[0])
--
http://mail.python.org/mailman/listinfo/python-list
