كيفية توثيق كود بايثون مع الدوكسيجين [مغلق]

Question

أحب Doxygen لإنشاء وثائق كود C أو PHP.لدي مشروع بايثون قادم وأعتقد أنني أتذكر أن بايثون ليس لديه مشروع /* .. */ التعليقات، ولديها أيضًا وسيلة التوثيق الذاتي الخاصة بها والتي يبدو أنها الطريقة البيثونية للتوثيق.

بما أنني على دراية بالدوكسيجين، كيف يمكنني استخدامه لإنتاج وثائق بايثون الخاصة بي؟هل هناك أي شيء على وجه الخصوص يجب أن أكون على علم به؟

Answer 1

هذا هو موثقة على موقع دوكسيجين, ولكن لتلخيص هنا:

يمكنك استخدام Doxygen لتوثيق كود Python الخاص بك.يمكنك إما استخدام بناء جملة سلسلة وثائق بايثون:

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

في هذه الحالة سيتم استخراج التعليقات بواسطة الدوكسيجين، لكن لن تتمكن من استخدام أي منها أوامر الدوكسيجين الخاصة.

أو يمكنك (على غرار لغات النمط C ضمن Doxygen) مضاعفة علامة التعليق (#) في السطر الأول قبل العضو:

## @package pyexample
#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

في هذه الحالة، يمكنك استخدام أوامر دوكسيجن الخاصة.لا يوجد وضع إخراج محدد في لغة Python، ولكن يبدو أنه يمكنك تحسين النتائج عن طريق الإعداد OPTMIZE_OUTPUT_JAVA ل YES.

بصراحة، أنا مندهش قليلاً من الفرق - يبدو أنه بمجرد أن يتمكن Doxygen من اكتشاف التعليقات في ## كتل أو كتل """، سيتم إنجاز معظم العمل وستكون قادرًا على استخدام الأوامر الخاصة في كلتا الحالتين.ربما يتوقعون من الأشخاص الذين يستخدمون """ أن يلتزموا بمزيد من ممارسات التوثيق Pythonic وهذا من شأنه أن يتعارض مع أوامر الدوكسيجين الخاصة؟

Answer 2

ال com.doxypy يتيح لك مرشح الإدخال استخدام جميع علامات تنسيق Doxygen تقريبًا بتنسيق Python docstring القياسي.أستخدمه لتوثيق إطار عمل كبير لتطبيقات ألعاب C++ وPython، وهو يعمل بشكل جيد.

Answer 3

Sphinx هي في الأساس أداة لتنسيق المستندات المكتوبة بشكل مستقل عن الكود المصدري، كما أفهمها.

لإنشاء مستندات API من مستندات Python، الأدوات الرائدة هي pdoc و pydoctor.إليك مستندات API التي أنشأها pydoctor لـ ملتوية و بازار.

بالطبع، إذا كنت تريد فقط إلقاء نظرة على المستندات أثناء عملك على الأشياء، فهناك "pydoc"أداة سطر الأوامر وكذلك help() الوظيفة المتوفرة في المترجم التفاعلي.

Answer 4

في النهاية، أمامك خياران فقط:

يمكنك إنشاء المحتوى الخاص بك باستخدام Doxygen، أو إنشاء المحتوى الخاص بك باستخدام Sphinx*.

1. دوكسيجين:إنها ليست الأداة المفضلة لمعظم مشاريع بايثون.ولكن إذا كان عليك التعامل مع مشاريع أخرى ذات صلة مكتوبة بلغة C أو C++، فقد يكون ذلك منطقيًا.لهذا يمكنك تحسين التكامل بين Doxygen وPython باستخدام com.doxypypy.

2. أبو الهول:الأداة الفعلية لتوثيق مشروع بايثون.لديك ثلاثة خيارات هنا:يدوي وشبه آلي (توليد كعب روتين) وأوتوماتيكي بالكامل (مثل دوكسيجين).

   1. للحصول على وثائق API اليدوية، لديك Sphinx com.autodoc.يعد هذا أمرًا رائعًا لكتابة دليل مستخدم يحتوي على عناصر مدمجة تم إنشاؤها بواسطة واجهة برمجة التطبيقات.
   2. لشبه التلقائي لديك أبو الهول ملخص تلقائي.يمكنك إما إعداد نظام البناء الخاص بك للاتصال بـ sphinx-autogen أو إعداد Sphinx الخاص بك باستخدام ملف autosummary_generate التكوين.سوف تحتاج إلى إعداد صفحة تحتوي على الملخصات التلقائية، ثم تحرير الصفحات يدويًا.لديك خيارات، لكن تجربتي مع هذا النهج هي أنه يتطلب الكثير من التكوين، وفي النهاية، حتى بعد إنشاء قوالب جديدة، وجدت أخطاء واستحالة تحديد ما تم الكشف عنه بالضبط كواجهة برمجة تطبيقات عامة وما لم يتم الكشف عنه.رأيي هو أن هذه الأداة جيدة لإنشاء كعب الروتين الذي سيتطلب تحريرًا يدويًا، وليس أكثر.يشبه الاختصار لينتهي في الدليل.
   3. اوتوماتيك كليا.لقد تم انتقاد هذا عدة مرات ولفترة طويلة لم يكن لدينا مولد Python API جيد آلي بالكامل ومتكامل مع Sphinx حتى ذلك الحين واجهة برمجة التطبيقات التلقائية جاء، وهو طفل جديد في الكتلة.يعد هذا هو الأفضل على الإطلاق لإنشاء واجهة برمجة التطبيقات التلقائية في Python (ملاحظة:الترويج للذات وقح).

هناك خيارات أخرى يجب ملاحظتها:

• يتنفس:بدأ هذا كفكرة جيدة جدًا، ويصبح منطقيًا عند العمل مع العديد من المشاريع ذات الصلة بلغات أخرى تستخدم Doxygen.تتمثل الفكرة في استخدام مخرجات Doxygen XML وإطعامها إلى Sphinx لإنشاء واجهة برمجة التطبيقات (API) الخاصة بك.لذلك، يمكنك الاحتفاظ بكل خيرات دوكسيجن وتوحيد نظام التوثيق في أبو الهول.رائع من الناحية النظرية.الآن، من الناحية العملية، آخر مرة قمت فيها بفحص المشروع لم يكن جاهزًا للإنتاج.
• pydoctor*:دقيق جدا.يولد الناتج الخاص به.لديه بعض التكامل الأساسي مع Sphinx وبعض الميزات الرائعة.

Answer 5

أداة توثيق أخرى جيدة جدًا هي أبو الهول.سيتم استخدامه للبايثون 2.6 القادم توثيق ويستخدم من قبل جانغو والكثير من مشاريع بايثون الأخرى.

من موقع سفنكس :

• تنسيقات الإخراج:HTML (بما في ذلك تعليمات Windows HTML) وLaTeX، لإصدارات PDF القابلة للطباعة
• مراجع تبادلية واسعة النطاق:العلامات الدلالية والروابط التلقائية للوظائف والفئات ومصطلحات المصطلحات وأجزاء مماثلة من المعلومات
• الهيكل الهرمي:تعريف سهل لشجرة المستندات، مع روابط تلقائية للأشقاء والآباء والأطفال
• المؤشرات التلقائية:الفهرس العام بالإضافة إلى فهرس الوحدة النمطية
• التعامل مع التعليمات البرمجية:تمييز تلقائي باستخدام أداة تمييز Pygments
• ملحقات:الاختبار التلقائي لمقتطفات التعليمات البرمجية، وإدراج سلاسل المستندات من وحدات Python، والمزيد