Comment définir l'affichage avec pour pydoc « MODULE DOCS »?

Question

La documentation pydoc de certains modules Python (comme math et sys) a une section "MODULE DOCS" qui contient un lien utile pour certains documents HTML:

Help on module math:

NAME
    math

FILE
    /sw/lib/python2.6/lib-dynload/math.so

MODULE DOCS
    /sw/share/doc/python26/html/math.html

Comment une telle section soit inclus dans vos propres modules?

Plus généralement, est-il un lieu où les variables reconnues par pydoc sont documentées?

Je n'ai pas pu trouver dans la source parce que le module math est une bibliothèque partagée, sur ma machine (OS X), et le module sys est construit en Python ... Toute aide serait grandement appréciée!

Answer 1

Après avoir regardé dans le code du module pydoc, je pense que le lien « MODULE DOCS » est disponible uniquement pour les modules standard, pas ceux personnalisés.

Voici le code correspondant:

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

Une valeur de retour de None est interprété comme un vide section "MODULE DOCS".

Answer 2

documentation du module est probablement le docstring du module . Ceci est une chaîne texte (ou texte restructuré ) apparaissant en haut de votre module. Voici un exemple.

"""
Module documentation.
"""

def bar():
    print "HEllo"

Ceci est pour les modules Python purs.

Pour les modules d'extension compilés (comme math), Vous passez le module docstring (comme une chaîne Python) comme 3ème argument Py_InitModule3 lorsque vous initialisant votre module. Cela fera la chaîne du module docstring. Vous pouvez voir cela se fait dans la source pour le module de calcul .