¿Cómo definir el “MÓDULO Docs” para su visualización con pydoc?

Question

La documentación pydoc de algunos módulos de Python (como math y sys) tiene una sección "MODULO Docs" que contiene un enlace útil para algunos documentos 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

¿Cómo puede una sección de este tipo se incluirá en sus propios módulos?

De forma más general, ¿hay un lugar en el que se documentan las variables reconocidas por pydoc?

Yo no era capaz de encontrar esto en la fuente ya que el módulo math es una biblioteca compartida, en mi máquina (OS X), y el módulo de sys está construido en Python ... Cualquier ayuda sería muy apreciada!

Answer 1

Después de mirar en el código del módulo pydoc, creo que el enlace "MÓDULO Docs" sólo está disponible para los módulos estándar, no los personalizados.

Este es el código correspondiente:

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 valor de retorno de Ninguno se interpreta como una sección vacía "MODULO Docs".

Answer 2

documentación del módulo es probablemente el cadena de documentación del módulo . Este es un texto plano (o reestructurado texto ) cadena se producen en la parte superior de su módulo. Aquí es un ejemplo.

"""
Module documentation.
"""

def bar():
    print "HEllo"

Se trata de los módulos Python puros.

Para los módulos de extensión compilados (como math), se pasa la cadena de documentación del módulo (como una cadena Python) como el tercero argumento para Py_InitModule3 cuando se está inicializando su módulo. Eso hará que la cadena de la cadena de documentación módulo. Esto se puede ver que se realiza en la fuente para el módulo de matemáticas aquí .