How to define the “MODULE DOCS” for display with pydoc?
Question
The pydoc documentation of some Python modules (like math
and sys
) has a "MODULE DOCS" section that contains a useful link to some HTML documentation:
Help on module math:
NAME
math
FILE
/sw/lib/python2.6/lib-dynload/math.so
MODULE DOCS
/sw/share/doc/python26/html/math.html
How can such a section be included in your own modules?
More generally, is there a place where the variables recognized by pydoc are documented?
I was not able to find this in the source because the math
module is a shared library, on my machine (OS X), and the sys
module is built in Python… Any help would be much appreciated!
Solution
After looking in the code of the pydoc
module, I think that the "MODULE DOCS" link is only available for standard modules, not custom ones.
Here is the relevant code:
def getdocloc(self, object):
"""Return the location of module docs or None"""
try:
file = inspect.getabsfile(object)
except TypeError:
file = '(built-in)'
docloc = os.environ.get("PYTHONDOCS",
"http://docs.python.org/library")
basedir = os.path.join(sys.exec_prefix, "lib",
"python"+sys.version[0:3])
if (isinstance(object, type(os)) and
(object.__name__ in ('errno', 'exceptions', 'gc', 'imp',
'marshal', 'posix', 'signal', 'sys',
'thread', 'zipimport') or
(file.startswith(basedir) and
not file.startswith(os.path.join(basedir, 'site-packages'))))):
if docloc.startswith("http://"):
docloc = "%s/%s" % (docloc.rstrip("/"), object.__name__)
else:
docloc = os.path.join(docloc, object.__name__ + ".html")
else:
docloc = None
return docloc
A return value of None is interpreted as an empty "MODULE DOCS" section.
OTHER TIPS
Module documentation is probably the docstring of the module. This is a plain text (or restructured text) string occurring at the top of your module. Here is an example.
"""
Module documentation.
"""
def bar():
print "HEllo"
This is for pure Python modules.
For compiled extension modules (like math
), You pass the module docstring (as a Python string) as the 3rd argument to Py_InitModule3
when you're initialising your module. That will make the string the module docstring. You can see this being done in the source for the math module here.