Submit Search
Upload
他人が書いたコードのリファレンスをSphinxで作る方法
•
Download as PPTX, PDF
•
1 like
•
2,250 views
T
Takeshi Sugiyama
Follow
PyConJP2021 Day2
Read less
Read more
Engineering
Report
Share
Report
Share
1 of 44
Download now
Recommended
なぜ、いま リレーショナルモデルなのか(理論から学ぶデータベース実践入門読書会スペシャル)
なぜ、いま リレーショナルモデルなのか(理論から学ぶデータベース実践入門読書会スペシャル)
Mikiya Okuno
ディープラーニングのフレームワークと特許戦争
ディープラーニングのフレームワークと特許戦争
Yosuke Shinya
PFNにおける研究開発(2022/10/19 東大大学院「融合情報学特別講義Ⅲ」)
PFNにおける研究開発(2022/10/19 東大大学院「融合情報学特別講義Ⅲ」)
Preferred Networks
合成変量とアンサンブル:回帰森と加法モデルの要点
合成変量とアンサンブル:回帰森と加法モデルの要点
Ichigaku Takigawa
画像局所特徴量と特定物体認識 - SIFTと最近のアプローチ -
画像局所特徴量と特定物体認識 - SIFTと最近のアプローチ -
MPRG_Chubu_University
Turtlebot3とrealsenseで作るお手軽移動ロボットros japan ug #23 関西勉強会
Turtlebot3とrealsenseで作るお手軽移動ロボットros japan ug #23 関西勉強会
Hiroaki Kaneda
【メタサーベイ】基盤モデル / Foundation Models
【メタサーベイ】基盤モデル / Foundation Models
cvpaper. challenge
Transformerを雰囲気で理解する
Transformerを雰囲気で理解する
AtsukiYamaguchi1
Recommended
なぜ、いま リレーショナルモデルなのか(理論から学ぶデータベース実践入門読書会スペシャル)
なぜ、いま リレーショナルモデルなのか(理論から学ぶデータベース実践入門読書会スペシャル)
Mikiya Okuno
ディープラーニングのフレームワークと特許戦争
ディープラーニングのフレームワークと特許戦争
Yosuke Shinya
PFNにおける研究開発(2022/10/19 東大大学院「融合情報学特別講義Ⅲ」)
PFNにおける研究開発(2022/10/19 東大大学院「融合情報学特別講義Ⅲ」)
Preferred Networks
合成変量とアンサンブル:回帰森と加法モデルの要点
合成変量とアンサンブル:回帰森と加法モデルの要点
Ichigaku Takigawa
画像局所特徴量と特定物体認識 - SIFTと最近のアプローチ -
画像局所特徴量と特定物体認識 - SIFTと最近のアプローチ -
MPRG_Chubu_University
Turtlebot3とrealsenseで作るお手軽移動ロボットros japan ug #23 関西勉強会
Turtlebot3とrealsenseで作るお手軽移動ロボットros japan ug #23 関西勉強会
Hiroaki Kaneda
【メタサーベイ】基盤モデル / Foundation Models
【メタサーベイ】基盤モデル / Foundation Models
cvpaper. challenge
Transformerを雰囲気で理解する
Transformerを雰囲気で理解する
AtsukiYamaguchi1
深層学習による自然言語処理入門: word2vecからBERT, GPT-3まで
深層学習による自然言語処理入門: word2vecからBERT, GPT-3まで
Yahoo!デベロッパーネットワーク
画像認識モデルを作るための鉄板レシピ
画像認識モデルを作るための鉄板レシピ
Takahiro Kubo
状態空間モデルの考え方・使い方 - TokyoR #38
状態空間モデルの考え方・使い方 - TokyoR #38
horihorio
畳み込みニューラルネットワークの高精度化と高速化
畳み込みニューラルネットワークの高精度化と高速化
Yusuke Uchida
PyTorchLightning ベース Hydra+MLFlow+Optuna による機械学習開発環境の構築
PyTorchLightning ベース Hydra+MLFlow+Optuna による機械学習開発環境の構築
Kosuke Shinoda
3次元計測とフィルタリング
3次元計測とフィルタリング
Norishige Fukushima
画像認識の初歩、SIFT,SURF特徴量
画像認識の初歩、SIFT,SURF特徴量
takaya imai
[DL輪読会]Learning Transferable Visual Models From Natural Language Supervision
[DL輪読会]Learning Transferable Visual Models From Natural Language Supervision
Deep Learning JP
SSII2022 [TS2] 自律移動ロボットのためのロボットビジョン〜 オープンソースの自動運転ソフトAutowareを解説 〜
SSII2022 [TS2] 自律移動ロボットのためのロボットビジョン〜 オープンソースの自動運転ソフトAutowareを解説 〜
SSII
Optimizer入門&最新動向
Optimizer入門&最新動向
Motokawa Tetsuya
SSII2021 [TS3] 機械学習のアノテーションにおける データ収集 〜 精度向上のための仕組み・倫理や社会性バイアス 〜
SSII2021 [TS3] 機械学習のアノテーションにおける データ収集 〜 精度向上のための仕組み・倫理や社会性バイアス 〜
SSII
先駆者に学ぶ MLOpsの実際
先駆者に学ぶ MLOpsの実際
Tetsutaro Watanabe
Motpy ros rosjp
Motpy ros rosjp
RayAr3
グラフィカルモデル入門
グラフィカルモデル入門
Kawamoto_Kazuhiko
CV分野におけるサーベイ方法
CV分野におけるサーベイ方法
Hirokatsu Kataoka
GiNZAで始める日本語依存構造解析 〜CaboCha, UDPipe, Stanford NLPとの比較〜
GiNZAで始める日本語依存構造解析 〜CaboCha, UDPipe, Stanford NLPとの比較〜
Megagon Labs
ベイジアンモデリングによるマーケティングサイエンス〜状態空間モデルを用いたモデリング
ベイジアンモデリングによるマーケティングサイエンス〜状態空間モデルを用いたモデリング
宏喜 佐野
IROS2020 survey
IROS2020 survey
robotpaperchallenge
イミュータブルデータモデル(入門編)
イミュータブルデータモデル(入門編)
Yoshitaka Kawashima
多様な強化学習の概念と課題認識
多様な強化学習の概念と課題認識
佑 甲野
211120 他人の書いたPythonスクリプトをステップ実行で理解する
211120 他人の書いたPythonスクリプトをステップ実行で理解する
Takuya Nishimoto
本気でPythonで宛名書きした話
本気でPythonで宛名書きした話
Satoshi Yamada
More Related Content
What's hot
深層学習による自然言語処理入門: word2vecからBERT, GPT-3まで
深層学習による自然言語処理入門: word2vecからBERT, GPT-3まで
Yahoo!デベロッパーネットワーク
画像認識モデルを作るための鉄板レシピ
画像認識モデルを作るための鉄板レシピ
Takahiro Kubo
状態空間モデルの考え方・使い方 - TokyoR #38
状態空間モデルの考え方・使い方 - TokyoR #38
horihorio
畳み込みニューラルネットワークの高精度化と高速化
畳み込みニューラルネットワークの高精度化と高速化
Yusuke Uchida
PyTorchLightning ベース Hydra+MLFlow+Optuna による機械学習開発環境の構築
PyTorchLightning ベース Hydra+MLFlow+Optuna による機械学習開発環境の構築
Kosuke Shinoda
3次元計測とフィルタリング
3次元計測とフィルタリング
Norishige Fukushima
画像認識の初歩、SIFT,SURF特徴量
画像認識の初歩、SIFT,SURF特徴量
takaya imai
[DL輪読会]Learning Transferable Visual Models From Natural Language Supervision
[DL輪読会]Learning Transferable Visual Models From Natural Language Supervision
Deep Learning JP
SSII2022 [TS2] 自律移動ロボットのためのロボットビジョン〜 オープンソースの自動運転ソフトAutowareを解説 〜
SSII2022 [TS2] 自律移動ロボットのためのロボットビジョン〜 オープンソースの自動運転ソフトAutowareを解説 〜
SSII
Optimizer入門&最新動向
Optimizer入門&最新動向
Motokawa Tetsuya
SSII2021 [TS3] 機械学習のアノテーションにおける データ収集 〜 精度向上のための仕組み・倫理や社会性バイアス 〜
SSII2021 [TS3] 機械学習のアノテーションにおける データ収集 〜 精度向上のための仕組み・倫理や社会性バイアス 〜
SSII
先駆者に学ぶ MLOpsの実際
先駆者に学ぶ MLOpsの実際
Tetsutaro Watanabe
Motpy ros rosjp
Motpy ros rosjp
RayAr3
グラフィカルモデル入門
グラフィカルモデル入門
Kawamoto_Kazuhiko
CV分野におけるサーベイ方法
CV分野におけるサーベイ方法
Hirokatsu Kataoka
GiNZAで始める日本語依存構造解析 〜CaboCha, UDPipe, Stanford NLPとの比較〜
GiNZAで始める日本語依存構造解析 〜CaboCha, UDPipe, Stanford NLPとの比較〜
Megagon Labs
ベイジアンモデリングによるマーケティングサイエンス〜状態空間モデルを用いたモデリング
ベイジアンモデリングによるマーケティングサイエンス〜状態空間モデルを用いたモデリング
宏喜 佐野
IROS2020 survey
IROS2020 survey
robotpaperchallenge
イミュータブルデータモデル(入門編)
イミュータブルデータモデル(入門編)
Yoshitaka Kawashima
多様な強化学習の概念と課題認識
多様な強化学習の概念と課題認識
佑 甲野
What's hot
(20)
深層学習による自然言語処理入門: word2vecからBERT, GPT-3まで
深層学習による自然言語処理入門: word2vecからBERT, GPT-3まで
画像認識モデルを作るための鉄板レシピ
画像認識モデルを作るための鉄板レシピ
状態空間モデルの考え方・使い方 - TokyoR #38
状態空間モデルの考え方・使い方 - TokyoR #38
畳み込みニューラルネットワークの高精度化と高速化
畳み込みニューラルネットワークの高精度化と高速化
PyTorchLightning ベース Hydra+MLFlow+Optuna による機械学習開発環境の構築
PyTorchLightning ベース Hydra+MLFlow+Optuna による機械学習開発環境の構築
3次元計測とフィルタリング
3次元計測とフィルタリング
画像認識の初歩、SIFT,SURF特徴量
画像認識の初歩、SIFT,SURF特徴量
[DL輪読会]Learning Transferable Visual Models From Natural Language Supervision
[DL輪読会]Learning Transferable Visual Models From Natural Language Supervision
SSII2022 [TS2] 自律移動ロボットのためのロボットビジョン〜 オープンソースの自動運転ソフトAutowareを解説 〜
SSII2022 [TS2] 自律移動ロボットのためのロボットビジョン〜 オープンソースの自動運転ソフトAutowareを解説 〜
Optimizer入門&最新動向
Optimizer入門&最新動向
SSII2021 [TS3] 機械学習のアノテーションにおける データ収集 〜 精度向上のための仕組み・倫理や社会性バイアス 〜
SSII2021 [TS3] 機械学習のアノテーションにおける データ収集 〜 精度向上のための仕組み・倫理や社会性バイアス 〜
先駆者に学ぶ MLOpsの実際
先駆者に学ぶ MLOpsの実際
Motpy ros rosjp
Motpy ros rosjp
グラフィカルモデル入門
グラフィカルモデル入門
CV分野におけるサーベイ方法
CV分野におけるサーベイ方法
GiNZAで始める日本語依存構造解析 〜CaboCha, UDPipe, Stanford NLPとの比較〜
GiNZAで始める日本語依存構造解析 〜CaboCha, UDPipe, Stanford NLPとの比較〜
ベイジアンモデリングによるマーケティングサイエンス〜状態空間モデルを用いたモデリング
ベイジアンモデリングによるマーケティングサイエンス〜状態空間モデルを用いたモデリング
IROS2020 survey
IROS2020 survey
イミュータブルデータモデル(入門編)
イミュータブルデータモデル(入門編)
多様な強化学習の概念と課題認識
多様な強化学習の概念と課題認識
Similar to 他人が書いたコードのリファレンスをSphinxで作る方法
211120 他人の書いたPythonスクリプトをステップ実行で理解する
211120 他人の書いたPythonスクリプトをステップ実行で理解する
Takuya Nishimoto
本気でPythonで宛名書きした話
本気でPythonで宛名書きした話
Satoshi Yamada
PythonのインストールからHello Worldまで
PythonのインストールからHello Worldまで
Kioto Hirahara
Python入門者の集い #6 Lightning Talk
Python入門者の集い #6 Lightning Talk
Katayanagi Nobuko
The tale of I and python / Python とのはなし
The tale of I and python / Python とのはなし
Takanori Suzuki
Python札幌 2012/06/17
Python札幌 2012/06/17
Shinya Okano
データ分析スクリプトのツール化入門 - PyConJP 2016
データ分析スクリプトのツール化入門 - PyConJP 2016
Akinori Kohno
Django から各種チャットツールに通知するライブラリを作った話
Django から各種チャットツールに通知するライブラリを作った話
Yusuke Miyazaki
Sphinx ではじめるドキュメント生活 2012 #pyconjp #sphinxconjp
Sphinx ではじめるドキュメント生活 2012 #pyconjp #sphinxconjp
Takeshi Komiya
プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022
プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022
Takayuki Shimizukawa
S06 t1 python学習奮闘記#4
S06 t1 python学習奮闘記#4
Takeshi Akutsu
アウトプットのすすめ
アウトプットのすすめ
KoichiHirai1
Sphinxを使って本を書こう #pyconjp 2012
Sphinxを使って本を書こう #pyconjp 2012
Takayuki Shimizukawa
ゼロから学ぶPython勉強会
ゼロから学ぶPython勉強会
sekikazu
191208 python-kansai-nishimoto
191208 python-kansai-nishimoto
Takuya Nishimoto
みんなのPython勉強会#43 Pyladies x Stapy ジョイントミートアップ #2
みんなのPython勉強会#43 Pyladies x Stapy ジョイントミートアップ #2
ManPingHe
Pyladies tokyo 20150123
Pyladies tokyo 20150123
Ai Makabi
(python)勉強会のすすめ
(python)勉強会のすすめ
Kioto Hirahara
Pythonのプロファイリング
Pythonのプロファイリング
ysakaguchi
Python for Beginners ( #PyLadiesKyoto Meetup )
Python for Beginners ( #PyLadiesKyoto Meetup )
Ai Makabi
Similar to 他人が書いたコードのリファレンスをSphinxで作る方法
(20)
211120 他人の書いたPythonスクリプトをステップ実行で理解する
211120 他人の書いたPythonスクリプトをステップ実行で理解する
本気でPythonで宛名書きした話
本気でPythonで宛名書きした話
PythonのインストールからHello Worldまで
PythonのインストールからHello Worldまで
Python入門者の集い #6 Lightning Talk
Python入門者の集い #6 Lightning Talk
The tale of I and python / Python とのはなし
The tale of I and python / Python とのはなし
Python札幌 2012/06/17
Python札幌 2012/06/17
データ分析スクリプトのツール化入門 - PyConJP 2016
データ分析スクリプトのツール化入門 - PyConJP 2016
Django から各種チャットツールに通知するライブラリを作った話
Django から各種チャットツールに通知するライブラリを作った話
Sphinx ではじめるドキュメント生活 2012 #pyconjp #sphinxconjp
Sphinx ではじめるドキュメント生活 2012 #pyconjp #sphinxconjp
プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022
プログラマーとの出会い - Hello, Programmer! at PyCon Kyushu 2022
S06 t1 python学習奮闘記#4
S06 t1 python学習奮闘記#4
アウトプットのすすめ
アウトプットのすすめ
Sphinxを使って本を書こう #pyconjp 2012
Sphinxを使って本を書こう #pyconjp 2012
ゼロから学ぶPython勉強会
ゼロから学ぶPython勉強会
191208 python-kansai-nishimoto
191208 python-kansai-nishimoto
みんなのPython勉強会#43 Pyladies x Stapy ジョイントミートアップ #2
みんなのPython勉強会#43 Pyladies x Stapy ジョイントミートアップ #2
Pyladies tokyo 20150123
Pyladies tokyo 20150123
(python)勉強会のすすめ
(python)勉強会のすすめ
Pythonのプロファイリング
Pythonのプロファイリング
Python for Beginners ( #PyLadiesKyoto Meetup )
Python for Beginners ( #PyLadiesKyoto Meetup )
他人が書いたコードのリファレンスをSphinxで作る方法
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.
12.
docstringをつける前に • 何をしているスクリプトなのかを理解するために読む • 読もうとすると,どうも気になるPEP8違反 •
演算子やカンマ周りのスペースの入れ方が適当 • めちゃめちゃ長い行 • 放任主義で育てられたせいでimport文が追加した順に並んでる • 処理内容と辻褄が合わないコメントや,間違ってはいないけど冗 長な処理も気になる
13.
放任主義で育てられたimportブロックの例 1ブロックにまとまってるだけ まだまし
14.
放任主義で育てられたimportブロックの例 Jupyter Notebook時代の名残り 新規Notebook作ると反射的に最初に 書いちゃうimport文
15.
放任主義で育てられたimportブロックの例 機能を書いていくうちに必要になったやつ
16.
放任主義で育てられたimportブロックの例 FlaskでWebアプリ化したときに追加
17.
放任主義で育てられたimportブロックの例 スクリプトを複数モジュールに分割したとき に追加 実はこのタイミングでflask.Blueprintは import不要になったけど残ってる
18.
放任主義で育てられたimportブロックの例 機能追加したときに必要になったやつ
19.
まずは最低限整える • PEP8準拠に • テストもないのにいきなりblackにかける勇気はない •
PyCharmの警告にしたがって粛々と修正 • mypyでチェックするのもいいね(いやそっちが普通か) • 間違ってるコメントはバグよりも害があるのでここで直す • ネットで拾ってコピペしたときのコメントが残っていることも • 処理そのものはいじらない • なんせテストがないので,いじったら検証が大変(今までどうしてたんだ) • 極端な話,set([‘a’, ‘b’, ‘c’]) を {‘a’, ‘b’, ‘c’}にしたくてもガマン • 気づいたことはtodoコメントを残したりissueあげておいたり
20.
docstringのスタイルを選ぶ • 3つのスタイル • reStructuredText
正直書きにくいし,ソースコードのままだと読みに くい • NumPy 垂直方向にかさむ • Google 説明が長いと水平方向にかさむ →どれでもOKだけど混在させない PyCharmは設定画面のPython Integrated Toolsで選んでおくと雛形 を自動生成してくれる ※docstringの詳細についてはPyConJP2019のku-muさんのトーク 「チームメイトのためにdocstringを書こう!!」が詳しくてわかりやすい https://www.slideshare.net/cocodrips/docstring-pyconjp2019
21.
スタイルの違い reStructuredTe xt NumPy Google 個人的にはNumPyスタイルが好 き (インデントの感じが)
22.
docstringを書くコツ • 大きい単位→小さい単位の順番に書く • まずはモジュール単位の役割を理解 •
モジュールのdicstringを書く • クラスの概要を理解 • クラスのdocstringを書く • メソッドなどクラス内関数のdocstringを書く • 関数の概要を理解 • 関数のdocstringを書く • 型の書き方とかわからなかったらまずは概要だけでも書く • とにかく一旦書き上げてしまう(更新は簡単)
23.
docstringを書くコツ • 大きい単位→小さい単位の順番に書く • まずはモジュール単位の役割を理解 •
モジュールのdicstringを書く • クラスの概要を理解 • クラスのdocstringを書く • メソッドなどクラス内関数のdocstringを書く • 関数の概要を理解 • 関数のdocstringを書く • 型の書き方とかわからなかったらまずは概要だけでも書く • とにかく一旦書き上げてしまう(更新は簡単) 結局気合い? でも気合い(勢い)も大事
24.
こんな感じ モジュールのdocstringの例 箇条書きはmarkdownで書くと Sphinxがいい感じに整形してくれる
25.
こんな感じ クラスのdocstringの例 「いやそもそもクラス作る意味!」 と思っても処理はいじらない
26.
こんな感じ 関数のdocstringの例 ここでもmarkdown活用
27.
いよいよSphinx 1. インストール • $
pip install –U sphinx 2. 雛形〜リファレンス作成 • $ sphinx-quickstart ./docs/ プロジェクト名,Author,Releaseを セット • conf.pyの編集 docstringからrstを自動生成するための設定 • index.rstの編集 読み込む対象を決めてmake 3. ちょっとカスタマイズ • config.pyがもっているバージョン情報を自動反映したい • お好みでテーマを変えてもOK
28.
sphinx-quickstart ビルドフォルダの置き方 こだわりがなければ[n]のままでOK
29.
sphinx-quickstart プロジェクト名,作者,リリース番号 適宜入力する
30.
sphinx-quickstart プロジェクトの言語 jaにすると例えば[source]が[ソース] になる。お好みで
31.
conf.pyの編集 • 以下3行を復活させる &
abspathの中は(’..’)に修正 • 拡張機能を追加(autodocとnapoleonとviewcode) • rstファイルの自動生成 • $ sphinx-apidoc -f -o ./docs . ←最後のドット忘れが ち注意 autodocはモジュールを importするので if __name__ ==~に なってないモジュールは注意
32.
index.rstの編集 • 半角スペース3つに続けてmodules • $
cd docs • $ make html
33.
ちょっと味付け • config.pyのVERSIONを取得して表示 • 好みに合わせてテーマを変える
34.
こんなんできました
35.
こんなんできました
36.
こんなんできました
37.
こんなんできました
38.
こんなんできました
39.
こんなんできました
40.
リファレンス完成!ばんざーい? • 陳腐化したドキュメントは誰も読まない • 今後の更新時にリファレンスも更新されなければ意味がない •
リリース手順の中でmake htmlを組み込む • Sさんはdevブランチからmasterブランチにマージするときに実行 • CIツールで実現してたらかっこよかったけど,できなかったので手順書 に書いた
41.
リファレンスできたらリファクタリング? • 他人が書いたコードのいけてないところが気になって,すぐにで も直したいのはやまやま • でもテストがないコードをそのまま使い続けるのは危険。テスト がないままいじるのはもっと危険 •
docstringを書く過程でコードをしっかり理解した今ならテストも 書けるはず • unittestでもpytestでもいいから1日も早くテストを書こう(本日 のスコープ外)
42.
その後のSさん(仮名) • テストも書き,リファクタリングも実施 • 何度か機能追加もおこなった •
最新化はmake html一発でOKなのでリファレンスは常に最新 • 新担当者の導入に使用したかったがまずはPython入門からだった • Python Boot Campをもとにアレンジした社内向け初心者講座開講 • また新たな保守対象のコード(docstringなし)が追加され, Sさん(仮名)の戦いは続く
43.
まとめ • docstringさえちゃんと書けばSphinxで簡単にいい感じのリファレン スを 作れる • まずはPEP8準拠とコメントの修正程度でリファレンスを完成させる •
リファクタリング後にmake htmlすれば常に最新リファレンスができ る • データ分析スクリプト書いてるみんな,繰り返し使うことが決まったら docstring(とテスト)を書こう!
44.
Enjoy!
Editor's Notes
ご静聴ありがとうございました
Download now