كيف تحدد "مستندات الوحدة النمطية" للعرض مع Pydoc؟

Question

وثائق 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 الوحدة النمطية بنيت في بيثون ... أي مساعدة سيكون موضع تقدير كبير!

Answer 1

بعد النظر في رمز 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

يتم تفسير قيمة إرجاع لا شيء على أنه قسم "مستندات الوحدة النمطية" الفارغة.

Answer 2

وثائق الوحدة هي ربما docstring من الوحدة النمطية. هذا نص عادي (أو نص إعادة هيكلة) سلسلة تحدث في الجزء العلوي من الوحدة النمطية. هنا مثال.

"""
Module documentation.
"""

def bar():
    print "HEllo"

هذا هو لوحدات بيثون النقية.

للحصول على وحدات التمديد المترجمة (مثل math) ، يمكنك تمرير Docstring الوحدة (كسلسلة ثعبان) كوسيطة ثالثة إلى Py_InitModule3 عند تهيئة الوحدة النمطية الخاصة بك. من شأنه أن يجعل السلسلة docstring الوحدة النمطية. يمكنك أن ترى هذا يتم في مصدر وحدة الرياضيات هنا.