Saya telah melihat beberapa gaya penulisan dokumen dengan Python, apakah ada gaya resmi atau "disetujui"?

Format

Dokumentasi python dapat ditulis mengikuti beberapa format seperti yang ditunjukkan oleh posting lainnya. Namun format dokumentasi Sphinx default tidak disebutkan dan didasarkan pada reStructuredText (reST) . Anda dapat memperoleh beberapa informasi tentang format utama dalam posting blog ini .

Perhatikan bahwa reST direkomendasikan oleh PEP 287

Berikut ini format utama yang digunakan untuk dokumen.

- Episode

Secara historis gaya seperti javadoc adalah lazim, sehingga diambil sebagai basis untuk Epydoc (dengan Epytextformat yang disebut ) untuk menghasilkan dokumentasi.

Contoh:

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

Saat ini, format yang mungkin lebih umum adalah format reStructuredText (reST) yang digunakan oleh Sphinx untuk menghasilkan dokumentasi. Catatan: ini digunakan secara default di JetBrains PyCharm (ketik triple quotes setelah mendefinisikan metode dan tekan enter). Ini juga digunakan secara default sebagai format output dalam Pyment.

Contoh:

"""
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 memiliki format sendiri yang sering digunakan. Ini juga dapat diartikan oleh Sphinx (mis. Menggunakan plugin Napoleon ).

Contoh:

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

Bahkan lebih banyak contoh

- Numpydoc

Perhatikan bahwa Numpy merekomendasikan untuk mengikuti numpydoc mereka sendiri berdasarkan format Google dan dapat digunakan oleh 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
"""

Konversi / Pembangkitan

Dimungkinkan untuk menggunakan alat seperti Pyment untuk secara otomatis menghasilkan dokumen ke proyek Python yang belum didokumentasikan, atau untuk mengkonversi dokumen yang ada (dapat mencampurkan beberapa format) dari satu format ke format lainnya.

Catatan: Contoh-contoh diambil dari dokumentasi Pyment

The panduan gaya Google berisi panduan gaya Python baik. Ini termasuk konvensi untuk sintaks dokumentasi yang dapat dibaca yang menawarkan panduan yang lebih baik daripada PEP-257. Sebagai contoh:

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

Saya ingin memperluas ini untuk juga memasukkan informasi jenis dalam argumen, seperti yang dijelaskan dalam tutorial dokumentasi Sphinx ini . Sebagai contoh:

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

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

Konvensi docstring ada dalam PEP-257 dengan lebih banyak detail daripada PEP-8.

Namun, dokumentasi tampaknya jauh lebih pribadi daripada bidang kode lainnya. Proyek yang berbeda akan memiliki standar sendiri.

Saya cenderung selalu memasukkan dokumen, karena mereka cenderung menunjukkan bagaimana menggunakan fungsi dan apa yang dilakukannya dengan sangat cepat.

Saya lebih memilih untuk menjaga hal-hal yang konsisten, terlepas dari panjang tali. Saya suka bagaimana kode terlihat ketika lekukan dan spasi konsisten. Itu artinya, saya menggunakan:

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

Lebih:

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

Dan cenderung tidak mengomentari baris pertama dalam dokumen yang lebih panjang:

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

Berarti saya menemukan dokumen yang mulai seperti ini menjadi berantakan.

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

Seperti tidak ada yang menyebutkannya: Anda juga dapat menggunakan Numpy Docstring Standard . Ini banyak digunakan dalam komunitas ilmiah.

• The spesifikasi format dari bersama-sama numpy dengan contoh
• Anda memiliki ekstensi sphinx untuk merendernya: numpydoc
• Dan contoh betapa indahnya tampilan dokumen yang terlihat: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

Ekstensi sphinx Napolean untuk mem-parsing Google-style docstring (direkomendasikan dalam jawaban @Nathan) juga mendukung docstring Numpy-style, dan membuat perbandingan singkat keduanya.

Dan terakhir contoh dasar untuk memberikan gambaran bagaimana tampilannya:

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 adalah standar pengkodean python resmi. Ini berisi bagian tentang docstring, yang mengacu pada PEP-257 - spesifikasi lengkap untuk docstrings.

Itu adalah Python; apapun itu . Pertimbangkan cara mempublikasikan dokumentasi Anda . Dokumen tidak terlihat kecuali bagi pembaca kode sumber Anda.

Orang-orang sangat suka menelusuri dan mencari dokumentasi di web. Untuk mencapainya, gunakan alat dokumentasi Sphinx . Ini adalah standar de-facto untuk mendokumentasikan proyek Python. Produk ini indah - lihat di https://python-guide.readthedocs.org/en/latest/ . Situs web Baca Dokumen akan meng-host dokumen Anda secara gratis.

Saya sarankan menggunakan program pep257 Python Vladimir Keleshev untuk memeriksa dokumen Anda terhadap PEP-257 dan Standar Numpy Docstring untuk menjelaskan parameter, pengembalian, dll.

pep257 akan melaporkan divergensi yang Anda buat dari standar dan disebut seperti pylint dan pep8.