في أبو الهول ، هل هناك طريقة لتوثيق المعلمات إلى جانب إعلانها؟

Question

أفضل توثيق كل معلمة (حسب الحاجة) على نفس السطر حيث أعلن المعلمة من أجل التقديم جاف

إذا كان لدي رمز مثل هذا:

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
   ):
    ...

كيف يمكنني تجنب تكرار المعلمات في سلسلة DOC والاحتفاظ بتفسيرات المعلمة؟

اريد تجنب:

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
    ):
    '''Foo does whatever.

    * flab_nickers - a series of under garments to process
    * needs_pressing - Whether the list of garments should all be pressed.
      [Default False.]

هل هذا ممكن في بيثون 2.6 أو بيثون 3 مع نوع من التلاعب بالديكور؟ هل هناك طريقة أخرى؟

Answer 1

اريد ان افعل هذا.

بدءا من هذا الرمز.

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
   ):
    ...

أود أن أكتب محللًا يمسك بتعريفات معلمة الوظيفة ويبني ما يلي:

def foo(
        flab_nickers, 
        has_polka_dots=False,
        needs_pressing=False,
   ):
   """foo

   :param flab_nickers: a series of under garments to process
   :type flab_nickers: list or tuple
   :param has_polka_dots: default False
   :type has_polka_dots: bool
   :param needs_pressing: default False, Whether the list of garments should all be pressed
   :type needs_pressing: bool
   """
    ...

هذه بعض معالجة regex مباشرة إلى الأمام لأنماط سلسلة الوسائط المختلفة لملء قالب الوثائق.

الكثير من ides python الجيدة (على سبيل المثال pycharm) فهم sphinx الافتراضي param التدوين وحتى العلم اسكواش/طرق في النطاق الذي يعتقد IDE لا يتوافق مع النوع المعلن.

لاحظ فاصلة إضافية في الكود ؛ هذا فقط لجعل الأمور متسقة. لا يضر ، وقد يبسط الأشياء في المستقبل.

يمكنك أيضًا محاولة استخدام برنامج التحويل البرمجي Python للحصول على شجرة Parse ، ومراجعتها وإبعاد رمز التحديث. لقد فعلت ذلك من أجل لغات أخرى (وليس بيثون) ، لذلك أعرف القليل عنها ، لكن لا أعرف مدى دعمها في بيثون.

أيضا ، هذا تحول لمرة واحدة.

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

تكون تعليقات sphinx أقرب إلى الجفاف لأنها في لغة ترميز RST ، مما يجعل معالجةها أسهل بكثير في استخدام أدوات ترشيح النص العادية في docutils.

إنها جافة فقط إذا كانت الأدوات يمكنها الاستفادة منها.

روابط مفيدة:https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions http://sphinx-doc.org/domains.html#id1

Answer 2

تهدف التعليقات التوضيحية إلى معالجة هذه المشكلة جزئيًا في بيثون 3:

http://www.python.org/dev/peps/pep-3107/

لست متأكدًا مما إذا كان هناك أي عمل في تطبيق هذه على sphinx حتى الآن.

Answer 3

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