Python での複数行コメント ドキュメントの書き方

docstring とは

ソフトウェア エンジニアリングにおいて、コーディングが実際に果たす役割は非常に小さく、ほとんどはドキュメントの作成など他の役割です。文書はコミュニケーションのツールです。
Python では、コード内にドキュメントを記述することを強くお勧めします。コードはドキュメントであり、より便利で、保守が簡単で、直感的で一貫性があります。
コードが書かれた後、ドキュメントも公開されます。実はMarkdownも同様の考え方を持っており、文章を書いた後は組版も完了します。
PEP 0257 の docstring の定義を見てください:

docstring は、
モジュール、関数、クラス、またはメソッド定義の最初のステートメントとして出現する文字列リテラルです。このような docstring は、
そのオブジェクトの __doc__ 特殊属性になります。
簡単に言うと、モジュール、関数、クラス、またはメソッドに現れる最初のステートメントは docstring です。これは自動的に属性 __doc__ になります。

def foo():
  """ This is function foo"""

は、foo.__doc__ を介してアクセスして、「これは関数 foo です」を取得できます。

さまざまな docstring スタイル:

Epytext

これは、かつては常に javadoc に似ていた人気のあるスタイルでした。

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

これは今人気のスタイル、ReSTスタイル、Sphinxの王道フォーマットです。私も個人的には、よりコンパクトなこのスタイルを使用するのが好きです。

"""
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スタイル

"""
This is a groups style docs.

Parameters:
  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スタイル)

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

docstringツールサードパーティライブラリpy ment

docstring の作成と変換に使用されます。
使用方法は、pymentを使用してパッチを生成し、パッチを適用します。

$ pyment test.py      #生成patch
$ patch -p1 < test.py.patch #打patch

詳細: https://github.com/dadadel/pyment

Sphinxのautodocを使用してdocstringからAPIドキュメントを自動的に生成します。手動で再度記述する必要はありません

すでにdocstringを書き込んでいますコードを記述します。 API ドキュメントの内容はこれに似ています。最初に 1 つずつコピーする必要がありますか?もちろん違います。 sphinxにはautodoc機能があります。
まず conf.py ファイルを編集します。
1. 「sphinx.ext.autodoc」拡張子が必要です。
2. ドキュメントを自動的に生成する必要があるモジュールがインポートできること、つまりパス内にあることを確認します。 。たとえば、sys.path.insert(0, os.path.abspath('../..')) が必要になる場合があります

次に、最初のファイルを作成し、

xxx_api module
---------------------

.. automodule:: xxx_api
  :members:
  :undoc-members:
  :show-inheritance:

make html コマンドを入力しますdocstring から開始できます。関連ドキュメントは Python で生成されます。最初に手動で再度記述する必要はありません。
その効果を見てください:

複数行のコメント ドキュメントに関連するその他の記事については、 Python の書き方については、PHP の中国語 Web サイトに注意してください。