පයිතන්හි විවිධ ලියවිලි ලේඛන කිහිපයක් මම දැක ඇත්තෙමි, නිල හෝ "එකඟ වූ" ශෛලියක් තිබේද?

ආකෘති

අනෙක් පෝස්ට් පෙන්වා ඇති පරිදි ආකෘති කිහිපයක් අනුගමනය කරමින් පයිතන් ඩොක්ස්ට්‍රිං ලිවිය හැකිය. කෙසේ වෙතත් පෙරනිමි ස්පින්ක්ස් ඩොක්ස්ට්‍රිං ආකෘතිය සඳහන් කර නැති අතර එය ප්‍රතිව්‍යුහගත ටෙක්ස්ට් (reST) මත පදනම් වේ . මෙම බ්ලොග් සටහනේ ප්‍රධාන ආකෘති පිළිබඳ තොරතුරු ඔබට ලබා ගත හැකිය .

PEST 287 මගින් ප්‍රතිස්ථාපනය නිර්දේශ කරනු ලැබේ

ලේඛ ලේඛන සඳහා ප්‍රධාන වශයෙන් භාවිතා කරන ආකෘති අනුගමනය කරයි.

- එපිටෙක්ස්ට්

ඓතිහාසිකව javadoc ඒ සඳහා පදනමක් ලෙස ගෙන ඒ ශෛලිය මෙන්, මෝසස්, Epydoc (හඳුන්වන සමග Epytextප්රලේඛනය උත්පාදනය කිරීමට ආකෘතිය).

උදාහරණයක්:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- නැවත

වර්තමානයේ, වඩාත් ප්‍රචලිත ආකෘතිය වන්නේ ප්‍රලේඛන ජනනය කිරීම සඳහා ස්පින්ක්ස් විසින් භාවිතා කරන ප්‍රතිව්‍යුහගත ටෙක්ස්ට් (reST) ආකෘතියයි . සටහන: එය පෙරනිමියෙන් ජෙට් බ්‍රේන්ස් පයිචාර්ම් හි භාවිතා කරයි (ක්‍රමයක් නිර්වචනය කිරීමෙන් පසු ත්‍රිත්ව උපුටා දැක්වීම් ටයිප් කර එන්ටර් ඔබන්න). එය පෙරනිමියෙන් පයිමන්ට් හි ප්‍රතිදාන ආකෘතියක් ලෙස භාවිතා කරයි.

උදාහරණයක්:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- ගූගල්

ගූගල් සතුව බොහෝ විට භාවිතා වන ඔවුන්ගේම ආකෘතියක් ඇත. එය ස්පින්ක්ස් (එනම් නැපෝලියන් ප්ලගිනය භාවිතා කිරීම ) මගින් අර්ථ නිරූපණය කළ හැකිය .

උදාහරණයක්:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

ඊටත් වඩා උදාහරණ

- නැම්පිඩොක්

ගූගල් ආකෘතිය මත පදනම්ව ස්පින්ක්ස් විසින් භාවිතා කළ හැකි ඔවුන්ගේම අංකපීඩොක් අනුගමනය කිරීමට නැම්පි නිර්දේශ කරන බව සලකන්න .

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

පරිවර්තනය / උත්පාදනය

තවමත් ලේඛනගත කර නොමැති පයිතන් ව්‍යාපෘතියකට ස්වයංක්‍රීයව ඩොක්ස්ට්‍රිං උත්පාදනය කිරීමට හෝ පවතින ලේඛණ (ආකෘති කිහිපයක් මිශ්‍ර කළ හැකිය) ආකෘතියකින් වෙනත් එකක් බවට පරිවර්තනය කිරීමට පයිමන්ට් වැනි මෙවලමක් භාවිතා කළ හැකිය.

සටහන: උදාහරණ ලබාගෙන ඇත්තේ පයිමන්ට් ප්‍රලේඛනයෙන් ය

මෙම ගූගල් විලාස මාර්ගෝපදේශකය විශිෂ්ට Python විලාස මාර්ගෝපදේශකය අඩංගු වේ. PEP-257 ට වඩා හොඳ මග පෙන්වීමක් ලබා දෙන කියවිය හැකි ඩොක්ස්ට්‍රිං සින්ටැක්ස් සඳහා සම්මුතීන් එයට ඇතුළත් ය . උදාහරණයක් වශයෙන්:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

මෙම ස්පින්ක්ස් ප්‍රලේඛන නිබන්ධනයේ විස්තර කර ඇති පරිදි තර්ක වල වර්ග තොරතුරු ඇතුළත් කිරීමට මෙය දීර් extend කිරීමට මම කැමතියි . උදාහරණයක් වශයෙන්:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

ඩොක්ස්ට්‍රිං සම්මුතීන් PEP-257 හි PEP-8 ට වඩා වැඩි විස්තර ඇත.

කෙසේ වෙතත්, ඩොක්ස්ට්‍රිං කේතයේ වෙනත් අංශවලට වඩා බොහෝ පෞද්ගලික බව පෙනේ. විවිධ ව්යාපෘති වලට ඔවුන්ගේම ප්රමිතියක් ඇත.

මම සෑම විටම docstrings ඇතුළත් කිරීමට නැඹුරු වෙමි, මන්ද ඔවුන් ශ්‍රිතය භාවිතා කරන්නේ කෙසේද සහ එය ඉතා ඉක්මණින් කරන්නේ කුමක්ද යන්න නිරූපණය කිරීමට නැඹුරු වන බැවිනි.

නූල් වල දිග නොතකා දේවල් ස්ථාවරව තබා ගැනීමට මම කැමැත්තෙමි. ඉන්ඩෙන්ටේෂන් සහ පරතරය ස්ථාවර වන විට පෙනුම කේත කරන්නේ කෙසේදැයි මම කැමතියි. ඒ කියන්නේ, මම භාවිතා කරන්නේ:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

අවසන්:

def sq(n):
    """Returns the square of n."""
    return n * n

පළමු පේළියේ දීර් do ලේඛනයන්හි අදහස් දැක්වීම අත්හැරීමට නැඹුරු වන්න:

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

තේරුම මේ වගේ ආරම්භ වන ලේඛනයන් අවුල් සහගත බව මට පෙනේ.

def sq(n):
    """Return the squared result. 
    ...

පෙනෙන විදිහට කිසිවෙකු එය සඳහන් කර නැත: ඔබට Numpy Docstring Standard ද භාවිතා කළ හැකිය . එය විද්‍යාත්මක ප්‍රජාව තුළ බහුලව භාවිතා වේ.

• මෙම ආකෘතිය පිරිවිතර numpy එකට සිට සමග උදාහරණයක්
• එය විදහා දැක්වීමට ඔබට ස්පින්ක්ස් දිගුවක් තිබේ: numpydoc
• විදැහුම්කරණය කරන ලද ලේඛනය කෙතරම් අලංකාර විය හැකිද යන්න පිළිබඳ උදාහරණයක්: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

ගූගල් විලාසිතාවේ ලේඛනය විග්‍රහ කිරීම සඳහා නැපෝලියන් ස්පින්ක්ස් දිගුව (@ නාතන්ගේ පිළිතුරෙන් නිර්දේශ කර ඇත) ද නැම්පි-ස්ටයිල් ඩොක්ස්ට්‍රිං සඳහා සහය දක්වයි , ඒ දෙකම කෙටි සංසන්දනයක් කරයි.

එය පෙනෙන්නේ කෙසේද යන්න පිළිබඳ අදහසක් ලබා දීමට මූලික උදාහරණයක් අවසන් කරන්න:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

PEP-8 යනු නිල පයිතන් කේතීකරණ ප්‍රමිතියයි. එය Docstrings පිළිබඳ කොටසක් අඩංගු වන අතර එය PEP-257 වෙත යොමු කරයි - docstrings සඳහා සම්පූර්ණ පිරිවිතර.

එය පයිතන්; ඕනෑම දෙයක් යනවා . ඔබේ ලියකියවිලි ප්‍රකාශයට පත් කරන්නේ කෙසේදැයි සලකා බලන්න . ඔබේ මූලාශ්‍ර කේතය කියවන අයට හැරෙන්නට ලේඛණ නොපෙනේ.

වෙබයේ ලේඛන සෙවීමට සහ සෙවීමට මිනිසුන් සැබවින්ම කැමතියි. එය සාක්ෂාත් කර ගැනීම සඳහා, ස්පින්ක්ස් නම් ප්‍රලේඛන මෙවලම භාවිතා කරන්න . එය පයිතන් ව්‍යාපෘති ලේඛනගත කිරීම සඳහා වන සත්‍ය ප්‍රමිතියයි. නිෂ්පාදිතය ලස්සනයි - https://python-guide.readthedocs.org/en/latest/ බලන්න . කියවන්න ඩොක්ස් වෙබ් අඩවිය ඔබේ ලියකියවිලි නොමිලයේ සපයනු ඇත.

පරාමිති, ප්‍රතිලාභ ආදිය විස්තර කිරීම සඳහා PEP-257 සහ Numpy Docstring Standard වලට එරෙහිව ඔබේ ලේඛනය පරීක්ෂා කිරීමට ව්ලැඩිමීර් කෙලෙෂෙව්ගේ pep257 Python වැඩසටහන භාවිතා කිරීමට මම යෝජනා කරමි .

pep257 මඟින් ඔබ ප්‍රමිතියෙන් සාදන අපසරනය වාර්තා කරන අතර එය පයිලින්ට් සහ පෙප් 8 ලෙස හැඳින්වේ.