ฉันเคยเห็นรูปแบบการเขียนเอกสารใน Python แตกต่างกันบ้างมีสไตล์เป็นทางการหรือ "เห็นด้วย"

รูปแบบ

Python docstrings สามารถเขียนได้หลายรูปแบบตามที่โพสต์อื่นแสดงให้เห็น แต่เริ่มต้นรูปแบบ docstring สฟิงซ์ไม่ได้กล่าวถึงและอยู่บนพื้นฐานreStructuredText (ส่วนที่เหลือ) คุณสามารถรับข้อมูลเกี่ยวกับรูปแบบหลักในโพสต์บล็อกนี้

โปรดทราบว่าแนะนำโดย reep โดยPEP 287

มีดังต่อไปนี้รูปแบบที่ใช้หลักสำหรับเอกสาร

- Epytext

ในอดีตมีลักษณะเหมือน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

ปัจจุบันรูปแบบที่แพร่หลายมากขึ้นอาจเป็นรูปแบบreStructuredText (reST) ที่ใช้โดยสฟิงซ์เพื่อสร้างเอกสาร หมายเหตุ: มันถูกใช้เป็นค่าเริ่มต้นใน JetBrains PyCharm (พิมพ์เครื่องหมายคำพูดสามเท่าหลังจากกำหนดวิธีการและกด Enter) นอกจากนี้ยังใช้เป็นค่าเริ่มต้นเป็นรูปแบบเอาต์พุตใน Pyment

ตัวอย่าง:

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

- Google

Google มีรูปแบบของตัวเองที่มักใช้ นอกจากนี้ยังสามารถตีความได้โดยสฟิงซ์ (เช่นใช้ปลั๊กอินนโปเลียน )

ตัวอย่าง:

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

แม้ตัวอย่างเพิ่มเติม

- Numpydoc

โปรดทราบว่า Numpy แนะนำให้ติดตามnumpydocของตนเองตามรูปแบบของ Google และใช้งานได้โดย Sphinx

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

แปลง / ฝ่ายผลิต

เป็นไปได้ที่จะใช้เครื่องมือเช่นPymentเพื่อสร้างเอกสารโดยอัตโนมัติไปยังโครงการ Python ที่ยังไม่มีการจัดทำเป็นเอกสารหรือเพื่อแปลงเอกสารที่มีอยู่ (สามารถผสมหลายรูปแบบ) จากรูปแบบหนึ่งไปยังอีกรูปแบบหนึ่ง

หมายเหตุ: ตัวอย่างที่นำมาจากเอกสาร Pyment

คู่มือสไตล์ Googleมีคู่มือสไตล์หลามที่ดีเยี่ยม มันมีข้อตกลงสำหรับไวยากรณ์ docstring ที่สามารถอ่านได้ซึ่งให้คำแนะนำที่ดีกว่า 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

ฉันชอบที่จะขยายสิ่งนี้เพื่อรวมข้อมูลประเภทในอาร์กิวเมนต์ตามที่อธิบายไว้ในเอกสารประกอบการสอนของสฟิงซ์นี้ ตัวอย่างเช่น:

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

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

ระเบียบของ Docstring อยู่ในPEP-257โดยมีรายละเอียดมากกว่า PEP-8

อย่างไรก็ตามเอกสารดูเหมือนจะเป็นส่วนตัวมากกว่าส่วนอื่น ๆ ของรหัส โครงการต่าง ๆ จะมีมาตรฐานของตนเอง

ฉันมักจะรวมถึงเอกสารเพราะพวกเขามักจะแสดงให้เห็นถึงวิธีการใช้ฟังก์ชั่นและสิ่งที่มันทำอย่างรวดเร็ว

ฉันชอบที่จะทำให้สิ่งต่าง ๆ สอดคล้องกันโดยไม่คำนึงถึงความยาวของสตริง ฉันชอบวิธีดูโค้ดเมื่อเยื้องและระยะห่างมีความสอดคล้องกัน หมายความว่าฉันใช้:

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

เกิน:

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

และมักจะแสดงความคิดเห็นในบรรทัดแรกในเอกสารที่ยาวกว่า:

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
• และตัวอย่างของ docstring ที่แสดงผลที่สวยงามนั้นมีลักษณะอย่างไร: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

ส่วนขยายนโปเลียนสฟิงซ์เพื่อแยกวิเคราะห์เอกสารสไตล์ Google (แนะนำในคำตอบของ @Nathan) ยังรองรับ docstring สไตล์แบบ Numpy และทำการเปรียบเทียบสั้น ๆของทั้งสอง

และสุดท้ายเป็นตัวอย่างพื้นฐานในการให้แนวคิดว่าหน้าตา:

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เป็นมาตรฐานการเข้ารหัสของไพ ธ อน มันมีส่วนเกี่ยวกับเอกสารซึ่งหมายถึงPEP-257 - ข้อกำหนดที่สมบูรณ์สำหรับเอกสาร

มันคือ Python อะไรไป พิจารณาวิธีการเผยแพร่เอกสารของคุณ เอกสารมองไม่เห็นยกเว้นผู้อ่านรหัสต้นฉบับของคุณ

คนชอบเรียกดูและค้นหาเอกสารบนเว็บ เพื่อให้บรรลุว่าใช้เครื่องมือเอกสารสฟิงซ์ เป็นมาตรฐานที่แท้จริงสำหรับการบันทึกโครงการ Python สินค้าที่มีความสวยงาม - ใช้เวลาดูที่https://python-guide.readthedocs.org/en/latest/ เว็บไซต์อ่านเอกสารจะโฮสต์เอกสารของคุณฟรี

ฉันแนะนำให้ใช้โปรแกรมpep257 Python ของ Vladimir Keleshev เพื่อตรวจสอบ docstrings ของคุณกับPEP-257และNumpy Docstring Standardเพื่ออธิบายพารามิเตอร์ผลตอบแทน ฯลฯ

pep257 จะรายงานความแตกต่างที่คุณทำจากมาตรฐานและเรียกว่าเช่น pylint และ pep8