1.
他人が書いたコードのリファレンスを
Sphinxで作る方法
PyConJP2021 2021-10-16
杉山 剛
@Soogie(すーぎー)

2.
自己紹介
• 事務系サラリーマン歴33年 主なツール：Excel
• Python歴7年 独学趣味プログラマー
• 最近は仕事（データ分析）でもPythonを使うようになった
• PyConJP2016，2018登壇
• Python Boot Camp TA×5回
• Python関連書籍を中心に出版前レビュー×14冊
レビュー依頼は断らない主義で，今も1冊レビュー中

3.
トーク内容
話すこと
• 他人が書いたPythonスクリプトにdocstringをつける（手動）
• Sphinxで簡単にリファレンスを作る
話さないこと
• docstring自動生成
• Sphinxの詳しい使い方
• type hintとの連動
※実体験に基づいてますがフィクションであり，実在する人物・アプリとは無関係です
※あくまで発表者個人の意見であり所属組織の方針を代表するものではありません

4.
Sさん（仮名）の日常
• 初老の事務系サラリーマン
• 若い頃からプログラミングが好きで独学
• ここ数年はRとPythonを行ったり来たり
• 社内では「Pythonいいぞ〜」とちょっと詳しそうな雰囲気をアピール
• データサイエンスの波到来→「Sさん確かPythonできたよね」
• Pythonを学ぶ後輩，書ける中途入社者と一緒に仕事でPython
• みんな独学。Git？コードレビュー？

5.
それは突然やってきた
• 後輩があらたまって「Sさん，ちょっとお話があります」

6.
それは突然やってきた
• 後輩があらたまって「Sさん，ちょっとお話があります」
• やっぱりね，そうだろうと思ってた
• となると困るのは例のWebアプリだな
• 「簡単な設計書つけときました〜」は信じないぞ

7.
それは突然やってきた
• 後輩があらたまって「Sさん，ちょっとお話があります」
• やっぱりね，そうだろうと思ってた
• となると困るのは例のWebアプリだな
• 「簡単な設計書つけときました〜」は信じないぞ
え，Pythonだからコードとコメントで十分？
• なに，2週間後？

8.
データ分析スクリプトあるある
• Jupyter Notebookでセル単位で試行錯誤
• Qiitaや技術系ブログからコピペしてきたコードをつなぎ合わせ
て
結果を出す。正しい結果が出ればよい
• 自分がわかればよいので，コメントも適当or書かない
• いい感じの分析スクリプトは共有され，個人用がいつの間にか
業務用に
• そのタイミングできれいにしたりテスト書いたり
・・・しないよね

9.
例のWEBアプリ
• 辞める後輩がいろいろ調べながら書いたデータ分析スクリプトを
別の後輩がFlaskでWebアプリ化
• コード書けない人も使うようになり業務用アプリとして本人が保守
• SさんはWebアプリ化する前に一度コードを眺めたことがある
• 眺めた時は1ファイルだったが今は複数モジュール構成
• ドキュメントなし
• ちなみにテストもないけど今日はその話じゃない

10.
そうだリファレンスを作ろう
• 自分がソースコード理解して保守できるようになってもこのまま
だと誰にも引き継げない
• がんばって丁寧に設計書を書いたとしても更新されなければ意
味がない
• Sphinxなら簡単にリファレンス作れるし，更新もmake一発らし
い
• そうだ，Sphinxでリファレンスを作ろう
https://www.sphinx-doc.org/ja/master/index.html

11.
docstringをつける前に
• 何をしているスクリプトなのかを理解するために読む
• 読もうとすると，どうも気になるPEP8違反
• 演算子やカンマ周りのスペースの入れ方が適当
• めちゃめちゃ長い行
• 放任主義で育てられたせいでimport文が追加した順に並んでる
• 処理内容と辻褄が合わないコメントや，間違ってはいないけど冗
長な処理も気になる

12.
放任主義で育てられたimportブロックの例
１ブロックにまとまってるだけ
まだまし

13.
放任主義で育てられたimportブロックの例
Jupyter Notebook時代の名残り
新規Notebook作ると反射的に最初に
書いちゃうimport文

14.
放任主義で育てられたimportブロックの例
機能を書いていくうちに必要になったやつ

15.
放任主義で育てられたimportブロックの例
FlaskでWebアプリ化したときに追加

16.
放任主義で育てられたimportブロックの例
スクリプトを複数モジュールに分割したとき
に追加
実はこのタイミングでflask.Blueprintは
import不要になったけど残ってる

17.
放任主義で育てられたimportブロックの例
機能追加したときに必要になったやつ

18.
まずは最低限整える
• PEP8準拠に
• テストもないのにいきなりblackにかける勇気はない
• PyCharmの警告にしたがって粛々と修正
• mypyでチェックするのもいいね（いやそっちが普通か）
• 間違ってるコメントはバグよりも害があるのでここで直す
• ネットで拾ってコピペしたときのコメントが残っていることも
• 処理そのものはいじらない
• なんせテストがないので，いじったら検証が大変（今までどうしてたんだ）
• 極端な話，set([‘a’, ‘b’, ‘c’]) を {‘a’, ‘b’, ‘c’}にしたくてもガマン
• 気づいたことはtodoコメントを残したりissueあげておいたり

19.
docstringのスタイルを選ぶ
• 3つのスタイル
• reStructuredText 正直書きにくいし，ソースコードのままだと読みに
くい
• NumPy 垂直方向にかさむ
• Google 説明が長いと水平方向にかさむ
→どれでもOKだけど混在させない
PyCharmは設定画面のPython Integrated Toolsで選んでおくと雛形
を自動生成してくれる
※docstringの詳細についてはPyConJP2019のku-muさんのトーク
「チームメイトのためにdocstringを書こう!!」が詳しくてわかりやすい
https://www.slideshare.net/cocodrips/docstring-pyconjp2019

20.
スタイルの違い
reStructuredTe
xt
NumPy Google
個人的にはNumPyスタイルが好
き
（インデントの感じが）

21.
docstringを書くコツ
• 大きい単位→小さい単位の順番に書く
• まずはモジュール単位の役割を理解
• モジュールのdicstringを書く
• クラスの概要を理解
• クラスのdocstringを書く
• メソッドなどクラス内関数のdocstringを書く
• 関数の概要を理解
• 関数のdocstringを書く
• 型の書き方とかわからなかったらまずは概要だけでも書く
• とにかく一旦書き上げてしまう（更新は簡単）

22.
docstringを書くコツ
• 大きい単位→小さい単位の順番に書く
• まずはモジュール単位の役割を理解
• モジュールのdicstringを書く
• クラスの概要を理解
• クラスのdocstringを書く
• メソッドなどクラス内関数のdocstringを書く
• 関数の概要を理解
• 関数のdocstringを書く
• 型の書き方とかわからなかったらまずは概要だけでも書く
• とにかく一旦書き上げてしまう（更新は簡単） 結局気合い？
でも気合い（勢い）も大事

23.
こんな感じ
モジュールのdocstringの例
箇条書きはmarkdownで書くと
Sphinxがいい感じに整形してくれる

24.
こんな感じ
クラスのdocstringの例
「いやそもそもクラス作る意味！」
と思っても処理はいじらない

25.
こんな感じ
関数のdocstringの例
ここでもmarkdown活用

26.
いよいよSphinx
1. インストール
• $ pip install –U sphinx
2. 雛形〜リファレンス作成
• $ sphinx-quickstart ./docs/ プロジェクト名,Author,Releaseを
セット
• conf.pyの編集 docstringからrstを自動生成するための設定
• index.rstの編集 読み込む対象を決めてmake
3. ちょっとカスタマイズ
• config.pyがもっているバージョン情報を自動反映したい
• お好みでテーマを変えてもOK

27.
sphinx-quickstart
ビルドフォルダの置き方
こだわりがなければ[n]のままでOK

28.
sphinx-quickstart
プロジェクト名，作者，リリース番号
適宜入力する

29.
sphinx-quickstart
プロジェクトの言語
jaにすると例えば[source]が[ソース]
になる。お好みで

30.
conf.pyの編集
• 以下3行を復活させる ＆ abspathの中は（’..’）に修正
• 拡張機能を追加（autodocとnapoleonとviewcode）
• rstファイルの自動生成
• $ sphinx-apidoc -f -o ./docs . ←最後のドット忘れが
ち注意
autodocはモジュールを
importするので
if __name__ ==～に
なってないモジュールは注意

31.
index.rstの編集
• 半角スペース3つに続けてmodules
• $ cd docs
• $ make html

32.
ちょっと味付け
• config.pyのVERSIONを取得して表示
• 好みに合わせてテーマを変える

33.
こんなんできました

34.
こんなんできました

35.
こんなんできました

36.
こんなんできました

37.
こんなんできました

38.
こんなんできました

39.
リファレンス完成！ばんざーい？
• 陳腐化したドキュメントは誰も読まない
• 今後の更新時にリファレンスも更新されなければ意味がない
• リリース手順の中でmake htmlを組み込む
• Sさんはdevブランチからmasterブランチにマージするときに実行
• CIツールで実現してたらかっこよかったけど，できなかったので手順書
に書いた

40.
リファレンスできたらリファクタリング？
• 他人が書いたコードのいけてないところが気になって，すぐにで
も直したいのはやまやま
• でもテストがないコードをそのまま使い続けるのは危険。テスト
がないままいじるのはもっと危険
• docstringを書く過程でコードをしっかり理解した今ならテストも
書けるはず
• unittestでもpytestでもいいから1日も早くテストを書こう（本日
のスコープ外）

41.
その後のSさん（仮名）
• テストも書き，リファクタリングも実施
• 何度か機能追加もおこなった
• 最新化はmake html一発でOKなのでリファレンスは常に最新
• 新担当者の導入に使用したかったがまずはPython入門からだった
• Python Boot Campをもとにアレンジした社内向け初心者講座開講
• また新たな保守対象のコード（docstringなし）が追加され，
Sさん(仮名)の戦いは続く

42.
まとめ
• docstringさえちゃんと書けばSphinxで簡単にいい感じのリファレン
スを
作れる
• まずはPEP8準拠とコメントの修正程度でリファレンスを完成させる
• リファクタリング後にmake htmlすれば常に最新リファレンスができ
る
• データ分析スクリプト書いてるみんな，繰り返し使うことが決まったら
docstring（とテスト）を書こう！

43.
Enjoy!