Как определить «Модульные документы» для отображения с PYDOC?

StackOverflow https://stackoverflow.com/questions/3078735

  •  28-09-2019
  •  | 
  •  

Вопрос

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

Это было полезно?

Решение

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

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

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

Другие советы

Модульная документация, вероятно, DOCSTRING модуля. Отказ Это простой текст (или Реструктурированный текст) Строка, возникающая в верхней части вашего модуля. Вот пример.

"""
Module documentation.
"""

def bar():
    print "HEllo"

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

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

Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top