Как определить «Модульные документы» для отображения с PYDOC?
Вопрос
Документация 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. Вы можете увидеть это, сделанное в источнике для математического модуля здесь.