自分が昔書いたコード、チームメイトが書いたコードがなにしているのかわからない...そんなことってよくありますよね。今回はそんな悩みを少しでも解決するため、コード内に書くドキュメントdocstringの書き方やドキュメントの自動生成方法を紹介していきます。

1. docstring !!
!1

2. • @cocodrips
• Jenkins
→
→AI
• :
PyDataTokyo
2

3. 1. docstring
2. docstring
3. docstring
. docstring

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

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

6. docstring
• Jupyter Notebook ?
help
6

7. docstring
•
•
• type
IDE (IDE )
•
7

8. docstring

9. 9
def func(arg1, arg2):
“”" *1 *
0
Parameters
----------
1 :
1
2 :
2
Returns
-------
"""

10. 10
def func(arg1, arg2):
“”" *1 *
0
Parameters
----------
1 :
1
2 :
2
Returns
-------
"""
1
※
doc

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

12. 12
• TypeHint
def func(arg1: int, arg2: str) -> bool:
"""
Parameters
----------
1 : 1
2 : 2
"""

13. 13
• Class docstring
class Hello:
"""
"""

14. 14
• module(.py ) docstring -
"""
"""

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

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

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

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

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

20. VS Code: autoDocsring
20

21. PyCharm:
21

22. docstring

23. Sphinx
23
•知的で美しいドキュメント
( )
• Sphinx Web
Flask

24. 24

25. $ git clone git@github.com:pallets/flask.git
# 依存ライブラリのインストール
$ python seup.py install
25
sphinx-apidoc import
!!!

26. sphinx-apidoc
26
# 設定ファイルを作る & ドキュメントの雛形を生成
$ sphinx-apidoc -F -a -o ./doc ./flask
doc
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
├── flask.rst
必要に応じて
設定ファイルを書き換え

27. !27
flask package
=============
…
Submodules
----------
flask.app module
----------------
.. automodule:: flask.app
:members:
:undoc-members:
:show-inheritance:
flask.app
flask.app
/

28. 28
$ cd doc
$ make html
$ open _build/html/index.html

29. !29

30. ^ω^
30

31. …
• Quick Start
•
•

32. 32

33. 33

34. 34

35. : docstring

36. •
(Google/Numpy)
•
docstring ?
• docstring PR
↑↑↑↑↑↑ ↑↑↑↑↑↑
36

37. doc-cov
•
37
$ doccov flask/flask -fmc
class 38 / 45 84.44%
module 19 / 19 100.00%
function 356 / 504 70.63%

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

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