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 Epytext
format 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