প্যারামিটার (গুলি) দিয়ে কোনও পদ্ধতি কীভাবে ডকুমেন্ট করবেন?

Question

পাইথনের ডকুমেন্টেশন স্ট্রিংগুলি ব্যবহার করে প্যারামিটারগুলির সাথে পদ্ধতিগুলি কীভাবে নথিভুক্ত করা যায়?

সম্পাদনা: পিইপি 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

সেখানে বেশ কয়েকটি 'স্ট্যান্ডার্ড' রয়েছে তবে একটি ব্যবহারিক পদ্ধতির উপর এবং বিশেষত যদি আপনি কিছু আনুষ্ঠানিক পছন্দ করেন তবে আমি স্পিনিক্সের পরামর্শ দেব । পাইচার্মের মধ্যে এটির সংহতকরণ ভাল কাঠামোগত ডকাস্ট্রিংগুলি বরং বেদনাদায়ক করে তোলে। আইএমএইচও

— জোজো

Answer 1

আমার অভিজ্ঞতা উপর ভিত্তি করে, numpy docstring নিয়মাবলী (PEP257 সুপারসেটও) বহুল-প্রচার করা হচ্ছে অনুসৃত নিয়মাবলী যে যেমন সরঞ্জাম, দ্বারা সমর্থিত স্পিংক্স ।

একটি উদাহরণ:

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

Comments

এটি আমার প্রত্যাশার কাছাকাছি। দুর্ভাগ্যক্রমে, আমি সরল পিইপি 257 বাছাই করেছি এবং আমার নিজস্ব কনভেনশন যুক্ত করেছি (অটোজেনারেটেড এইচটিএমএল / পিডিএফ ডকুমেন্টেশনগুলি ছাড়ার জন্য)। তবে, পরের বার, আমি এই সমাধানটি বেছে নেব। ধন্যবাদ।

— ডেভিড Andreoletti

আমি যখন আপনার প্রস্তাবিত ডক্ট্রিং প্রসেসিংয়ের চেষ্টা করি তখন স্ফিংস অভিযোগ করেন SEVERE: Unexpected section title- আপনি কি স্পিনাক্সকে এটিকে আরও সুখী করার কোনও উপায় জানেন?

— ব্র্যান্ডন রোডস

@ ব্র্যান্ডনরোডস এই স্পিনিক্সের সাথে এই সম্মেলনগুলি ব্যবহার করার বিষয়ে এই লিঙ্কগুলির সাথে লিঙ্ক করেছে: github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

— ভ্লাদিমির কেলেশেভ

বাস্তবে এর আগেও একটি জায়গা নিখোঁজ রয়েছে Description। আমি সেই নপি ডকুমেন্টেশনটি যাচাই করেছিলাম, কারণ আমি সঙ্গে সঙ্গে লক্ষ্য করেছি এবং ভেবেছিলাম "এক সেকেন্ড অপেক্ষা করুন, এটি তিনটি স্থান কেন ? এটি অদ্ভুত Who তিনটি স্পেস কে ব্যবহার করবেন?"

— জেলফির কালটস্টল

প্রশ্নটি জিজ্ঞাসা করার সময়ে এটিই সেরা উত্তর হতে পারে তবে আমি মনে করি এখনকার (২০১ 2017 সালের শেষের দিকে), স্পিনেক্স বিজয়ী হয়ে উঠেছে।

— অ্যালেক্স এল

Answer 2

যেহেতু ডকাস্ট্রিংগুলি ফর্ম-ফর্ম, তাই আপনি এপিআই ডকুমেন্টেশন তৈরি করতে কোড পার্স করতে যা ব্যবহার করেন তার উপর এটি নির্ভর করে।

আমি স্পিঙ্কস মার্কআপের সাথে পরিচিত হওয়ার পরামর্শ দেব , যেহেতু এটি ব্যাপকভাবে ব্যবহৃত হয় এবং পাইথন প্রকল্পগুলি নথিভুক্ত করার জন্য ডি-ফ্যাক্টো স্ট্যান্ডার্ড হয়ে উঠছে, কারণ অল্প অংশে চমৎকার রিডথডোকস.আর.এস পরিষেবাটি। পাইথনের স্নিপেট হিসাবে স্পিংক্স ডকুমেন্টেশন থেকে একটি উদাহরণ প্যারাফ্রেস করতে :

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:সোর্স কোড থেকে ডকুমেন্টিংয়ের সময় আপনি কেবল ব্যবহার করতে পারেন ।

স্বাভাবিকভাবেই, API গুলি নথিভুক্ত করার জন্য অন্যান্য সরঞ্জাম রয়েছে। আরও ক্লাসিক ডক্সিজেন রয়েছে যা \param কমান্ড ব্যবহার করে তবে সেগুলি স্পিঞ্জের মতো পাইথন কোডটি নথিতে নকশাকৃত নয়।

মনে রাখবেন যে এখানে একটি অনুরূপ উত্তর সহ একই প্রশ্ন রয়েছে ...

Comments

এটিই স্টাইলটি পাইকার্মের মন্তব্যে অটোজেনারেশন ডিফল্টরূপে ব্যবহৃত হয়েছে

— জোশিয়াহ

স্টাফের তালিকার মতো যৌগিক ধরণের সিনট্যাক্স সম্পর্কে কী?

— ম্যাটানস্টার

তাহলে এটি একটি list।

— অরণকাত

Answer 3

কনভেনশন:

• পিইপি 257 ডকস্ট্রিং কনভেনশনস
• পিইপি 287 পুনর্গঠিত পাঠ্য ডক্ট্রিং ফর্ম্যাট

সরঞ্জাম:

• ইপিডোক: পাইথনের জন্য স্বয়ংক্রিয় এপিআই ডকুমেন্টেশন জেনারেশন
• sphinx.ext.autodoc - ডকাস্ট্রিং থেকে ডকুমেন্টেশন অন্তর্ভুক্ত করুন
• পাইচার্মের ডকাস্ট্রিংয়ের জন্য কিছু দুর্দান্ত সমর্থন রয়েছে

---

আপডেট: পাইথন ৩.৩ থেকে আপনি টাইপ ইঙ্গিতগুলি ব্যবহার করতে পারেন যা একটি কমপ্যাক্ট, মেশিন-পঠনযোগ্য সিনট্যাক্স:

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`.

    """

এই বাক্য গঠনটির মূল সুবিধাটি হ'ল এটি ভাষা দ্বারা সংজ্ঞায়িত করা হয় এবং এটি দ্ব্যর্থহীন, তাই পাইচার্মের মতো সরঞ্জামগুলি সহজেই এ থেকে সুবিধা নিতে পারে।

Comments

যদিও এই উত্তরটি এখন সর্বাধিক উর্ধ্বমুখী, তবুও উপরের কোন পিইপি কোনও পদ্ধতির আর্গুমেন্টের ধরণ নির্দিষ্ট করার জন্য একটি কনভেনশন সরবরাহ করে না।

— কোরিয়ান্ডার

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
    """

এখন, কিছু সম্মেলন রয়েছে, তবে পাইথন সেগুলির কোনও প্রয়োগ করে না। কিছু প্রকল্পের নিজস্ব সম্মেলন রয়েছে have ডকাস্ট্রিংয়ের সাথে কাজ করার জন্য কিছু সরঞ্জাম নির্দিষ্ট কনভেনশনগুলি অনুসরণ করে।

Answer 5

আপনি যদি নিজের কোডটি নথির জন্য স্ফিংস ব্যবহার করার পরিকল্পনা করেন তবে এটি তাদের 'স্বাক্ষর' বৈশিষ্ট্য সহ আপনার পরামিতিগুলির জন্য দুর্দান্ত ফর্ম্যাট এইচটিএমএল ডক্স তৈরি করতে সক্ষম। http://sphinx-doc.org/domains.html#signatures

Answer 6

মূল স্রোতটি হ'ল এখানে অন্যান্য উত্তরগুলি ইতিমধ্যে উল্লেখ করেছে, সম্ভবত স্পিনক্সের সাথে চলেছে যাতে আপনি সেই অভিনব ডকুমেন্টগুলি পরে তৈরি করতে স্পিনক্স ব্যবহার করতে পারেন।

বলা হচ্ছে, আমি ব্যক্তিগতভাবে মাঝে মাঝে ইনলাইন মন্তব্য শৈলীর সাথে যাই go

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

এটি কি অফিসিয়াল সিনট্যাক্স? এটি অত্যন্ত কার্যকর, তবে আমি এটি অফিসিয়াল ডক্স /

— পিইপিগুলিতে

আমি এটিও জানতে চাই, যদি এটির জন্য কোনও পিইপি থাকে।

— ড্রিমফ্ল্যাশার

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

— মার্ক হর্ভাথ

এটি ডকুমেন্টেশন হিসাবে কাজ করে না। আপনি যদি আপনার প্যাকেজটির মতো মন্তব্য করেন এবং কোনও পাইচার্ম ব্যবহারকারী এটি ডাউনলোড করেন তবে তারা আপনার ডকুমেন্টেশন অ্যাক্সেস না করে প্রতিটি প্যারাম কী করে তা যাচাই করতে সক্ষম হবে না - যা আপনি কোনও সফ্টওয়্যার দিয়ে তৈরি করতে সক্ষম হবেন না। যদি না আপনি নিজের তৈরি না করেন। এজন্য ওপি ডক্ট্রিংয়ে এটি নির্দিষ্ট করার জন্য বলেছে। দুঃখিত এত দেরীতে।

এটা ঠিক ভয়াবহ।

— মাইকেল ওয়াল্টারস