पैरामीटर (एस) के साथ एक विधि का दस्तावेज कैसे करें?

Question

पायथन के दस्तावेज़ स्ट्रिंग्स का उपयोग करके मापदंडों के साथ दस्तावेज़ कैसे करें?

EDIT: PEP 257 इसका उदाहरण देता है:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

क्या यह सम्मेलन अधिकांश पायथन डेवलपर्स द्वारा उपयोग किया जाता है?

Keyword arguments:
<parameter name> -- Definition (default value if any)

मुझे उम्मीद थी कि कुछ और थोड़ा औपचारिक होगा जैसे कि

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    @param: real The real part (default 0.0)
    @param: imag The imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

पर्यावरण : पायथन 2.7.1

Comments

क्या आपने पीईपी 257 पढ़ा है? python.org/dev/peps/pep-0257

— NPE

वहाँ कई 'मानक' हैं, लेकिन एक व्यावहारिक दृष्टिकोण पर और खासकर यदि आप कुछ औपचारिक पसंद करते हैं, तो मैं स्फिंक्स की सिफारिश करूंगा । Pycharm में इसका एकीकरण दर्द रहित बल्कि अच्छी तरह से संरचित डोकस्ट्रिंग्स उत्पन्न करता है। IMHO

— jojo

Answer 1

मेरे अनुभव के आधार पर, खस्ता डॉकस्ट्रिंग कन्वेंशन (PEP257 सुपरसेट) सबसे व्यापक रूप से फैले हुए कन्वेंशन हैं जो कि उपकरण द्वारा समर्थित हैं, जैसे कि स्फिंक्स ।

एक उदाहरण:

Parameters
----------
x : type
    Description of parameter `x`.

Comments

यह वही है जो मैंने उम्मीद की थी। दुर्भाग्य से, मैंने सादा पीईपी 257 उठाया और अपना स्वयं का अधिवेशन (ऑटोजेनरेटेड HTML / पीडीएफ प्रलेखन खोने की कीमत पर) जोड़ा। हालांकि, अगली बार, मैं इस समाधान को चुनूंगा। धन्यवाद।

— डेविड आंद्रेलेटी 5

जब मैं आपके सुझाए गए डॉक्सस्ट्रिंग को संसाधित करने का प्रयास करता हूं, तो स्फिंक्स शिकायत करता है SEVERE: Unexpected section title- क्या आप जानते हैं कि स्फिंक्स को इससे खुश करने का कोई तरीका है?

— ब्रैंडन रोड्स

@BrandonRhodes इस लिंक Sphinx के साथ इन सम्मेलनों का उपयोग करने के बारे में बात करता है: github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

— व्लादिमीर केलशेव

दरअसल इससे पहले एक जगह लापता है Description। मैंने खस्ता दस्तावेज की जाँच की, क्योंकि मैंने तुरंत देखा और सोचा "एक सेकंड रुको, यह तीन जगह क्यों है ? यह अजीब है। कौन इन रिक्त स्थान का उपयोग करेगा?"

— ज़ेल्फ़िर कलस्टहल

सवाल पूछे जाने के समय यह सबसे अच्छा जवाब हो सकता है, लेकिन मुझे लगता है कि अब (2017 के अंत में), स्फिंक्स विजयी हुआ है।

— एलेक्स एल

Answer 2

चूंकि डॉकस्ट्रिंग्स फ्री-फॉर्म हैं, यह वास्तव में इस बात पर निर्भर करता है कि आप एपीआई प्रलेखन उत्पन्न करने के लिए कोड का उपयोग क्या करते हैं।

मैं Sphinx मार्कअप से परिचित होने की सलाह दूंगा , क्योंकि यह व्यापक रूप से उपयोग किया जाता है और उत्कृष्ट readthedocs.org सेवा के कारण भाग में पायथन परियोजनाओं के दस्तावेजीकरण के लिए वास्तविक मानक बन रहा है । पाइथन स्निपेट के रूप में स्फिंक्स डॉक्यूमेंटेशन से एक उदाहरण को समझने के लिए :

def send_message(sender, recipient, message_body, priority=1):
   '''
   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring
   '''

यह मार्कअप दस्तावेजों और अधिक के बीच क्रॉस- रेफरेंसिंग का समर्थन करता है । ध्यान दें कि स्फिंक्स प्रलेखन का उपयोग करता है (जैसे) :py:attr:जबकि आप :attr:स्रोत कोड से दस्तावेजीकरण करते समय उपयोग कर सकते हैं ।

स्वाभाविक रूप से, एपीआई को दस्तावेज करने के लिए अन्य उपकरण हैं। वहाँ अधिक क्लासिक Doxygen है जो \param आदेशों का उपयोग करता है, लेकिन उन विशेष रूप से Python कोड को दस्तावेज़ करने के लिए डिज़ाइन नहीं किया गया है जैसे Sphinx है।

ध्यान दें कि एक समान प्रश्न के साथ यहां एक समान उत्तर है ...

Comments

यह शैली है जिसका उपयोग PyCharm की टिप्पणी ऑटोगेनेरेशन द्वारा डिफ़ॉल्ट रूप से किया जाता है

— जोशिया योडर

सामान की सूची जैसे समग्र प्रकार के वाक्य रचना के बारे में क्या?

— मटनस्टर

तो यह एक है list।

— anarcat

Answer 3

कन्वेंशनों:

• पीईपी 257 डॉकस्ट्रिंग कन्वेंशन
• PEP 287 reStructuredText Docstring प्रारूप

उपकरण:

• एपिडोक: पायथन के लिए स्वचालित एपीआई प्रलेखन पीढ़ी
• sphinx.ext.autodoc - डॉकस्ट्रिंग्स से प्रलेखन शामिल करें
• PyCharm को डॉकस्ट्रिंग्स के लिए कुछ अच्छा समर्थन है

---

अपडेट: पायथन 3.5 के बाद से आप टाइप संकेत का उपयोग कर सकते हैं जो एक कॉम्पैक्ट, मशीन-पठनीय वाक्यविन्यास है:

from typing import Dict, Union

def foo(i: int, d: Dict[str, Union[str, int]]) -> int:
    """
    Explanation: this function takes two arguments: `i` and `d`.
    `i` is annotated simply as `int`. `d` is a dictionary with `str` keys
    and values that can be either `str` or `int`.

    The return type is `int`.

    """

इस सिंटैक्स का मुख्य लाभ यह है कि यह भाषा द्वारा परिभाषित किया गया है और यह असंदिग्ध है, इसलिए PyCharm जैसे उपकरण आसानी से इसका लाभ उठा सकते हैं।

Comments

यद्यपि यह उत्तर अब सबसे अधिक उत्क्रमित हो गया है, ऊपर दिए गए PEPs में से कोई भी एक विधि के तर्कों को निर्दिष्ट करने के लिए एक कन्वेंशन प्रदान नहीं करता है।

— धनिया

Answer 4

अजगर डॉक्टर स्ट्रिंग्स स्वतंत्र रूप हैं , आप इसे किसी भी तरह से दस्तावेज़ कर सकते हैं।

उदाहरण:

def mymethod(self, foo, bars):
    """
    Does neat stuff!
    Parameters:
      foo - a foo of type FooType to bar with.
      bars - The list of bars
    """

अब, कुछ सम्मेलन हैं, लेकिन अजगर उनमें से किसी को भी लागू नहीं करता है। कुछ परियोजनाओं के अपने सम्मेलन हैं। डॉकस्ट्रिंग के साथ काम करने के लिए कुछ उपकरण विशिष्ट सम्मेलनों का भी पालन करते हैं।

Answer 5

यदि आप अपने कोड को दस्तावेज करने के लिए स्फिंक्स का उपयोग करने की योजना बनाते हैं, तो यह उनके 'हस्ताक्षर' सुविधा के साथ आपके मापदंडों के लिए अच्छी तरह से स्वरूपित HTML डॉक्स बनाने में सक्षम है। http://sphinx-doc.org/domains.html#signatures

Answer 6

मुख्य धारा यह है, जैसा कि अन्य उत्तर यहां पहले ही बता चुके हैं, शायद स्फिंक्स रास्ते से जा रहे हैं ताकि आप बाद में उन फैंसी दस्तावेजों को उत्पन्न करने के लिए स्फिंक्स का उपयोग कर सकें।

कहा जा रहा है, मैं व्यक्तिगत रूप से कभी-कभी इनलाइन टिप्पणी शैली के साथ जाता हूं।

def complex(  # Form a complex number
        real=0.0,  # the real part (default 0.0)
        imag=0.0  # the imaginary part (default 0.0)
        ):  # Returns a complex number.
    """Form a complex number.

    I may still use the mainstream docstring notation,
    if I foresee a need to use some other tools
    to generate an HTML online doc later
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    other_code()

यहाँ एक और उदाहरण, कुछ छोटे विवरणों के साथ इनलाइन का उल्लेख किया गया है:

def foo(  # Note that how I use the parenthesis rather than backslash "\"
          # to natually break the function definition into multiple lines.
        a_very_long_parameter_name,
            # The "inline" text does not really have to be at same line,
            # when your parameter name is very long.
            # Besides, you can use this way to have multiple lines doc too.
            # The one extra level indentation here natually matches the
            # original Python indentation style.
            #
            # This parameter represents blah blah
            # blah blah
            # blah blah
        param_b,  # Some description about parameter B.
            # Some more description about parameter B.
            # As you probably noticed, the vertical alignment of pound sign
            # is less a concern IMHO, as long as your docs are intuitively
            # readable.
        last_param,  # As a side note, you can use an optional comma for
                     # your last parameter, as you can do in multi-line list
                     # or dict declaration.
        ):  # So this ending parenthesis occupying its own line provides a
            # perfect chance to use inline doc to document the return value,
            # despite of its unhappy face appearance. :)
    pass

लाभ (@ मार्क-हॉरथ पहले से ही एक अन्य टिप्पणी में बताया गया है) हैं:

• सबसे महत्वपूर्ण बात, पैरामीटर और उनका डॉक्टर हमेशा एक साथ रहते हैं, जो निम्नलिखित लाभ लाता है:
• कम टाइपिंग (चर नाम दोहराने की आवश्यकता नहीं)
• चर को बदलने / हटाने पर आसान रखरखाव। आपके द्वारा कुछ पैरामीटर का नाम बदलने के बाद कुछ अनाथ पैरामीटर डॉक्टर अनुच्छेद नहीं होगा।
• और लापता टिप्पणी खोजने के लिए आसान है।

अब, कुछ सोच सकते हैं कि यह शैली "बदसूरत" दिखती है। लेकिन मैं कहूंगा कि "बदसूरत" एक व्यक्तिपरक शब्द है। कहने का एक और अधिक न्यूट्रल तरीका है, यह शैली मुख्यधारा नहीं है, इसलिए यह आपको कम परिचित लग सकती है, इस प्रकार कम आरामदायक है। फिर, "सहज" भी एक व्यक्तिपरक शब्द है। लेकिन मुद्दा यह है, ऊपर वर्णित सभी लाभ उद्देश्य हैं। यदि आप मानक तरीके का पालन करते हैं तो आप उन्हें प्राप्त नहीं कर सकते।

उम्मीद है कि भविष्य में किसी दिन, एक डॉक्टर जनरेटर उपकरण होगा जो इस तरह की इनलाइन शैली का भी उपभोग कर सकता है। वह गोद लेने की गाड़ी चलाएगा।

पुनश्च: जब भी मैं फिट देखता हूं तो यह उत्तर इनलाइन टिप्पणियों का उपयोग करने की मेरी अपनी पसंद से लिया गया है। मैं एक शब्दकोश में भी दस्तावेज़ के लिए एक ही इनलाइन शैली का उपयोग करता हूं ।

Answer 7

टाइप-हंट उत्तर ( https://stackoverflow.com/a/9195565/2418922 ) पर निर्माण करना , जो मानकों के प्रकारों को दस्तावेज करने के लिए एक बेहतर संरचित तरीका प्रदान करता है, दोनों प्रकारों और मापदंडों के विवरणों को दस्तावेज करने के लिए एक संरचित तरीका मौजूद है।

def copy_net(
    infile: (str, 'The name of the file to send'),
    host: (str, 'The host to send the file to'),
    port: (int, 'The port to connect to')):

    pass

उदाहरण से अपनाया गया: https://pypi.org/project/autocommand/

Comments

क्या यह एक आधिकारिक वाक्यविन्यास है? यह सुपर उपयोगी है, हालांकि मैं इसे आधिकारिक डॉक्स / पीईपी में नहीं पा सकता ...

— tori Raviv

मैं यह जानना चाहूंगा कि अगर इसके लिए कोई पीईपी है।

— ड्रीमफ्लैशर

Answer 8

डॉकस्ट्रिंग केवल इंटरैक्टिव वातावरण के भीतर उपयोगी होते हैं, जैसे कि पायथन शेल। जब ऐसी वस्तुओं का दस्तावेज़ीकरण किया जा रहा है जो अंतःक्रियात्मक रूप से उपयोग नहीं की जा रही हैं (जैसे आंतरिक ऑब्जेक्ट, फ्रेमवर्क कॉलबैक), तो आप नियमित टिप्पणियों का भी उपयोग कर सकते हैं। यहाँ एक शैली है जिसका उपयोग मैं आइटमों पर अप्रत्यक्ष टिप्पणियों को लटकाने के लिए करता हूं, प्रत्येक अपनी लाइन पर, ताकि आप जान सकें कि टिप्पणी इस पर लागू हो रही है:

def Recomputate \
  (
    TheRotaryGyrator,
      # the rotary gyrator to operate on
    Computrons,
      # the computrons to perform the recomputation with
    Forthwith,
      # whether to recomputate forthwith or at one's leisure
  ) :
  # recomputates the specified rotary gyrator with
  # the desired computrons.
  ...
#end Recomputate

आप डॉकस्ट्रिंग्स के साथ इस तरह का काम नहीं कर सकते।

Comments

ओह, यह एक बदसूरत लग रहा है।

— मिशा अकोवंतसेव

बदसूरत हाँ? दिलचस्प विचार ... हाँ भी।

— डेविड

चर के लिए इनलाइन टिप्पणियां बहुत ही समझदार हैं, कम टाइपिंग (चर नाम को दोहराने की आवश्यकता नहीं है), चर को बदलने / हटाने पर आसान रखरखाव ... लापता टिप्पणी खोजने में आसान। इसे हस्ताक्षर के नीचे उचित डॉकस्ट्रिंग के साथ जोड़ देंगे। +1

— मार्क होर्वथ

यह प्रलेखन के रूप में काम नहीं करता है। यदि आप अपने पैकेज को इस तरह से टिप्पणी करते हैं और एक PyCharm उपयोगकर्ता इसे डाउनलोड करता है, तो वे यह जांचने में सक्षम नहीं होंगे कि प्रत्येक पैराम आपके दस्तावेज़ तक पहुँच के बिना क्या करता है - जिसे आप किसी भी सॉफ़्टवेयर के साथ उत्पन्न नहीं कर पाएंगे। जब तक आप अपना नहीं बनाते। इसलिए ओपी इसे डॉकस्ट्रिंग में निर्दिष्ट करने के लिए कहता है। माफ़ करना इतनी देर।

यह सिर्फ भयानक है।

— माइकल वाल्टर्स