docstringとは、コード内に書くドキュメントです。 docstringを書いておくことによってクラスや関数の役割を伝えることができます。 初心者の方や、分析でPythonを使ってる方たちにはあまり馴染みがないかもしれません。 メンテナンスしやすいコードを書くための1つの術として、 今回はdocstringについて - どんなことを書くべきなのか - どんな書き方があるのか - どんな情報を埋め込めるのか ということをお話したいと思います。

1. docstring !!
!1

2. docstring
• Python
2
def f(arg1):
""" """
pass

3. • @cocodrips
•
→
→MLOps
• :
PyDataTokyo
3

4. 1. docstring
2. docstring
3. docstring
. DocString

5. docstring
• Python
5
def f(arg1):
""" """
pass

6. docstring
6
>>> help(f)
Help on function f:
f(arg1)
• docstring help

7. docstring
• Jupyter Notebook ?
help
7

8. Docstring
•
•
• type
IDE (IDE )
•
8

9. 9

10. docstring

11. 11
def func(arg1, arg2):
“”" 1
0
:param arg1: arg1
:type arg1: int #arg1
:param arg2: arg2
:type arg2: str #arg2
:rtype: bool #
:return:
"""

12. 12
•
def func(arg1, arg2):
“”” ””"

13. 13
• TypeHint
def func(arg1: int, arg2: str) -> bool:
"""
:param arg1: arg1
:param arg2: arg2
:return:
"""

14. 14
• module(.py ) docstring -
"""
"""
• Class docstring
class Hello:
"""
"""

15. docstring
3
• ReStructuredText
• NumPy Style
• Google Style
15

16. ReStructuredText(reST)
16
def func(arg1, arg2):
"""
:param arg1: 1
:type arg1: 1
:param arg2: 2
:type arg2: 2
:return:
:rtype:
"""

17. X
def func(arg1: , arg2: ): ->
"""
:param arg1: 1
:param arg2: 2
:return:
"""
ReStructuredText - TypeHints

18. NumPy style
17
def func(arg1, arg2):
"""
Parameters
----------
arg1 : 1
1
arg2 : 2
2
Returns
-------
"""
•
•

19. NumPy style - TypeHints
X
def func(arg1: , arg2: ) -> :
"""
Parameters
----------
arg1 :
1
arg2 :
2
Returns
-------
"""

20. Google Style
18
def func(arg1, arg2):
"""
Args:
arg1 ( 1 ): 1
arg2 ( 2 ): 2
Returns:
:
"""

21. 19
• ReStructuredText
•
• NumPy Style
•
• Google Style
•

22. 20
• ReStructuredText
•
• NumPy Style
•
• Google Style
•
TypeHints

23. 21
• ReStructuredText
•
• NumPy Style
•
• Google Style
•
TypeHints

24. 22
def func(arg1: , arg2: ): ->
"""
:param arg1: 1
:param arg2: 2
:return:
"""
ReStructuredText - TypeHints

25. PyCharm:
23

26. VS Code: autoDocsring
24

27. docstring

28. Sphinx
26
•知的で美しいドキュメント
( )
•

29. ^ω^
27

30. class Person:
""" """
def __init__(self, age: int, name: str):
self.age = age
self.name = name
def rest_doc_sample(age: int, name: str) -> Person:
"""Person
:param age:
:param name:
:return: Person
"""
# ...
return Person(age, name)
28
sample_package/simple_rest.py

31. $ pip install Sphinx sphinx-autodoc-typehints
# 依存ライブラリのインストール
$ python setup.py install
X
sphinx-apidoc import

32. sphinx-apidoc
29
# 設定ファイルを作る & ドキュメントの雛形を生成
$ sphinx-apidoc -F -a -o ./doc ./sample_package
doc
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
設定ファイル
• Extensionsに以下を追加
• sphinx_autodoc_typehints
• テーマを変更
• sphinx_rtd_theme
• Numpy/Google Styleを
採用する場合は拡張が必要

33. 30
$ cd doc
$ make html
$ open _build/html/index.html

34. !31

35. …
• Quick Start
•
•

36. 33

37. 34

38. : DocString

39. DocString
•
=> TypeHints + reST
• CI branch
GitHub Pages
• docstring PR
↑↑↑↑↑↑ ↑↑↑↑↑↑
36

40. DocString
•
=> TypeHints + reST
• CI branch
GitHub Pages
• docstring PR
↑↑↑↑↑↑ ↑↑↑↑↑↑
37

41. doc-cov
Pull request
38
# CI内で以下を実行
$ doccov <package> -fmc --output csv > doccov.csv
$ doccov-report doccov.csv

42. Pull Request / Issue
39
$ pip install doc-cov