Edited at

GoogleスタイルのPython Docstringの入門


前置き

本記事では、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