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!

Answer 1

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.

Answer 2

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.