前置き
本記事では、Googleスタイル形式でのPython Docstringの書き方について必要最低限に絞って説明する。
これから、Python Docstringを覚えようとしているエンジニアの参考になれば、幸いである。
Python Docstringとは
Pythonにおけるクラスや、メソッド(関数)についての説明を記載したコメント文のこと。
Docstringは、__doc__という変数に格納されている。
以下は、printメソッドのDocstringを表示させたもの。
>>> print(print.__doc__)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
自作したクラスや、メソッドにDocstringを記載しておくと、
IDE上に補足情報として表示させることや、Sphinxを使用して、ソースコードの仕様書を自動作成することが可能になる。
Sphinxとは
Sphinxは、reStructuredTextという形式で記載されたテキストをHTML、
PDFやepubなどの様々な形式へ変換することができるOSSのドキュメント生成ツール。
Pythonの公式ドキュメントはSphinxを使って書かれている。
Sphinxを用いると、Pythonのソースコード上からPython Docstringのコメント文を抽出して、
ソースコード仕様書を自動生成することが可能。
Sphixを使用した、Docstringの活用方法は下記を参照。
https://qiita.com/futakuchi0117/items/4d3997c1ca1323259844
Googleスタイル
Googleが提唱したDocstringの記法の一つ。
Docstringの記法にはreStructuredTextスタイル，Numpyスタイル，Googleスタイルの3つがある。
本記事では、Googleスタイルについて説明する。
GoogleスタイルのPython Docstring
Sphinxのサンプルコード
SphinxのHPから、Googleスタイル形式で記載されたサンプルコードを閲覧することができる。
上記のソースコードをSphinxでhtmlに変換すると下記のようになる。
日本語のサンプルコード
先程のサンプルコードを元に、要点のみを抜粋した日本語のサンプルコードと、ソースコードをSphinxでhtmlに変換したものを下記に記す。
#!/usr/bin/python
# -*- coding: utf-8 -*-
"""モジュールの説明タイトル
* ソースコードの一番始めに記載すること
* importより前に記載する
Todo:
TODOリストを記載
* conf.pyの``sphinx.ext.todo`` を有効にしないと使用できない
* conf.pyの``todo_include_todos = True``にしないと表示されない
"""
import json
import inspect
class testClass() :
"""クラスの説明タイトル
クラスについての説明文
Attributes:
属性の名前 (属性の型): 属性の説明
属性の名前 (:obj:`属性の型`): 属性の説明.
"""
def print_test(self, param1, param2) :
"""関数の説明タイトル
関数についての説明文
Args:
引数の名前 (引数の型): 引数の説明
引数の名前 (:obj:`引数の型`, optional): 引数の説明.
Returns:
戻り値の型: 戻り値の説明 (例 : True なら成功, False なら失敗.)
Raises:
例外の名前: 例外の説明 (例 : 引数が指定されていない場合に発生 )
Yields:
戻り値の型: 戻り値についての説明
Examples:
関数の使い方について記載
>>> print_test ("test", "message")
test message
Note:
注意事項などを記載
"""
print("%s %s" % (param1, param2) )
if __name__ == '__main__':
test_object = testClass()
test_object.print_test("test", "message")
基本的なコメントの書き方
- コメントを複数行のコメントブロック「"""」で囲む
- 「"""」の右隣にタイトルを記載する
- Docstringの対象となるのは、 モジュール、クラス、関数(メソッド)の3つ
モジュールの記載方法
ソースコードの冒頭に、ソースコード全体つまり、モジュールの説明を記載する。
注意点としては、コメント文を除いたソースコードの一番始めに記載する必要がある。
※ importより前に記載する必要がある。
#!/usr/bin/python
# -*- coding: utf-8 -*-
"""モジュールの説明タイトル
モジュールの説明
"""
クラスの記載方法
下記のように、クラス定義の下の行に記載する。
class testClass() :
"""クラスの説明タイトル
クラスについての説明文
"""
関数(メソッド)の記載方法
下記のように関数定義の下の行に記載する。
def print_test(self, param1, param2) :
"""関数の説明タイトル
関数についての説明文
"""
セクションの説明
Googleスタイルでは、Attributes, Args、Returns、Yieds、Raises、Examples、Note、Todoという用途別に定義されたセクションがある。
Attributesセクション
クラスの属性の型、名前など、クラスの属性の説明を記載する。
Attributes:
属性の名前 (属性の型): 属性の説明
属性の名前 (:obj:`属性の型`): 属性の説明.
Argsセクション
引数の名前、型、optional(省略可能)かどうかなど、引数の説明を記載するセクション。
- インスタンスを示すselfは、Argsセクションには記載せず、省略する
- 省略可能な引数は、下記のようにoptionalを記載する
- Sphinxでhtmlファイルに変換すると、Args → Parametersに変更される
Args:
引数の名前 (引数の型): 引数の説明
引数の名前 (:obj:`引数の型`, optional): 引数の説明.
Returnsセクション
retrun文を使用した関数の戻り値を記載するセクション。
Returns:
戻り値の型: 戻り値の説明 (例 : True なら成功, False なら失敗.)
Yieldsセクション
yeild文を使用した関数の戻り値を記載するセクション。
Yields:
戻り値の型: 戻り値についての説明
Raisesセクション
例外処理に対する説明を記載するセクション。
Raises:
例外の名前: 例外の説明 (例 : 引数が指定されていない場合に発生 )
Examplesセクション
関数、クラスの実行例について記載するセクション。
Examples:
関数の使い方について記載
>>> print_test ("test", "message")
test message
- Examplesだけでなく、Exampleでも可
- クラス、メソッド以外の箇所で使用する場合は、下記のように
::でコードブロックにする必要がある -
\はエスケープ文字なので、コードブロック中に\を表示させる場合、\\と記載する
Example:
関数の使い方について記載
::
$ python main.py \\
"arg1" \\
"args2" \\
Noteセクション
注釈について記載するセクション。
例えば、「このコードは、Python2系では動作しません」などのような注意事項を記載するといいだろう。
Note:
注意事項などを記載
Todoセクション
Todoリストを記載するためのセクション。
実装予定の処理など、後から実施する作業などはここに記載する。
Todo:
TODOリストを記載
* conf.pyの``sphinx.ext.todo`` を有効にしないと使用できない
* conf.pyの``todo_include_todos = True``にしないと表示されない
Shphixで変換後のドキュメントに表示させるには、
Sphinxの設定ファイルconf.pyを編集し、下記のように、
拡張機能[sphinx.ext.todo]を有効にする必要がある。
extensions = [ 'sphinx.ext.todo' ]
todo_include_todos = True