Как определить «MODULE DOCS» для отображения с помощью pydoc? - PullRequest
Новая
       16

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

1 голос
/ 20 июня 2010

Документация pydoc для некоторых модулей Python (например, math и sys) имеет раздел "MODULE 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 ... Любая помощь будет принята с благодарностью!

Ответы [ 2 ]

3 голосов
/ 24 июня 2010

После просмотра кода модуля 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 интерпретируется как пустой раздел "MODULE DOCS".

0 голосов
/ 20 июня 2010

Документация модуля, вероятно, является строкой документа модуля .Это строка простого текста (или реструктурированный текст ), расположенная в верхней части вашего модуля.Вот пример. 

"""
Module documentation.
"""

def bar():
    print "HEllo"

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

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

...