Как определить «MODULE DOCS» для отображения с pydoc?

Question

pydoc документация некоторых модулей Python (как math и sys) есть раздел «МОДУЛЬ DOCS», который содержит полезную ссылку на какую-то 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 

Как может такой раздел будет включен в ваших собственных модулях ?

В целом, есть ли место, где зафиксированы переменные, распознанные pydoc?

Я не смог найти это в источнике, потому что модуль math является общей библиотекой, на моей машине (OS X), и модуль sys построен на Python ... Любая помощь будет очень признательна!

Answer 1

После просмотра кода модуля pydoc, я думаю, что ссылка «MODULE DOCS» доступна только для стандартных модулей, а не для пользовательских.

Вот соответствующий код:

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 

Возвращаемое значение None интерпретируется как пустой «модуль» DOCS секции.

Answer 2

Документация по модулю, вероятно, docstring of the module. Это текстовая строка (или restructured text), встречающаяся в верхней части вашего модуля. Вот пример.

""" 
Module documentation. 
""" 

def bar(): 
    print "HEllo" 

Это для чистых модулей Python.

Для скомпилированных модулей расширения (например, math) вы передаете модуль docstring (как строку Python) в качестве третьего аргумента в Py_InitModule3, когда вы инициализируете свой модуль. Это создаст строку docstring модуля. Вы можете видеть, что это делается в источнике для математического модуля here.