Come definire il “MODULO DOCS” per la visualizzazione con pydoc?

Question

La documentazione pydoc di alcuni moduli Python (come math e sys) ha una sezione "MODULO DOCS" che contiene un collegamento utile per alcuni documenti 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

Come può un tale sezione essere incluso nei propri moduli?

Più in generale, c'è un luogo in cui sono documentate le variabili riconosciute da pydoc?

Non è stato in grado di trovare questo nella fonte perché il modulo math è una libreria condivisa, sulla mia macchina (OS X), e il modulo sys è costruito in Python ... Qualsiasi aiuto sarebbe molto apprezzato!

Answer 1

Dopo aver guardato nel codice del modulo pydoc, penso che il link "MODULO DOCS" è disponibile solo per i moduli standard, non la consuetudine quelli.

Ecco il codice in questione:

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

Un valore restituito di None viene interpretato come una sezione vuota "MODULO DOCS".

Answer 2

documentazione del modulo è probabilmente il docstring del modulo . Si tratta di un testo semplice (o ristrutturato testo ) stringa che si verificano nella parte superiore del modulo. Ecco un esempio.

"""
Module documentation.
"""

def bar():
    print "HEllo"

Questo è per moduli Python puri.

Per moduli di espansione compilati (come math), si passa la docstring del modulo (come una stringa Python) come il terzo argomento a Py_InitModule3 quando stai inizializzazione il modulo. Ciò renderà la stringa il modulo docstring. Si può vedere questo essere fatto in origine per il modulo matematico qui .