チームメイトのためにdocstringを書こう
ただのコメントではなくコード内ドキュメント
Jupyterだとf?と?をつける（裏でhelpを読みに行く）
書くと嬉しい
クラスや関数の役割がわかって嬉しい
実装と同じところにあるので直し忘れにくい
型を書くとIDEAにより補完される（型ヒントと同じ）
Sphinxでドキュメントを自動生成（後述）
基本的な書き方
reSTスタイルを紹介
概要だけ残してもよい
型ヒント & docstringでparamとreturnの説明
モジュールやクラスにも書ける
docstringの3つのスタイル
reStructuredTextスタイル
ドキュメント生成・型ヒントを書く前提だとおすすめ（スライド23）
型ヒント + reST
docstringからtypeの指定がなくなる（スッキリ）
標準的
:param arg1: :type int:
Numpyやscikit-learn
セクション（Parameters, Returns, Exception, Example）
縦に長くなりがち
横に長くなる代わりにシンプルに書ける（ku-muさん使っていたとのこと）
エディタの設定
PyCharmはテンプレートを設定できる（3連クォートで起動）
sample_package/simple_rest.py を例に
sphinx-apidoc -F -a -o ./doc ./sample_package
ドキュメントの雛形（conf.pyなど）を作る（quickstartのようなものなのか！）
conf.pyのextensionsにも指定
公開にはいくつか手作業が発生（Quick startページなど）
Docstringを書く文化の作り方
採用するスタイルを決める
CIでドキュメント自動生成 & GitHub Pagesなど
doccov-reportでPull requestにdocstringカバレッジが表示される
質疑
docstringのlinter？
チームではエディタの設定を統一している
（たしかに探せばありそうな気がする）
doctest
（Exampleの役割を果たしそうなので使ってみたい）
（Sphinxのdoctest拡張は賢いですよ〜）
関連
Effective Python 第2版
https://youtu.be/2A3gRyT54Wc