Hi all,
I'm posting partly so my problem and solution might be more easily found by google, and partly out of mere curiosity.
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.)
It turns out that I was using '''triple single quotes''' and pydoc only pulls a description out from module docstrings that are formatted in """triple double quotes""". I've poked about with google, and cannot find any explanation of why pydoc should treat the two cases differently. Anyone have an idea?
I do see that both <http://www.python.org/peps/pep-0008.html> -- Style Guide for Python Code and <http://www.python.org/peps/pep-0257.html> -- Docstring Conventions suggest triple double, so I guess it is my fault. But still, those PEP's have the tone of suggestions, and since the two quoting schemes are semantically equivalent . . .
I do prefer the look of triple-single, but oh well. My attempts to google for an answer didn't come up with anything, so perhaps this post will help someone else, if nothing else :-)
Best to all,
Brian vdB
-- http://mail.python.org/mailman/listinfo/python-list
