Suche senden
Hochladen
他人が書いたコードのリファレンスをSphinxで作る方法
•
Als PPTX, PDF herunterladen
•
1 gefällt mir
•
2,260 views
T
Takeshi Sugiyama
Folgen
PyConJP2021 Day2
Weniger lesen
Mehr lesen
Ingenieurwesen
Melden
Teilen
Melden
Teilen
1 von 44
Jetzt herunterladen
Empfohlen
位置データもPythonで!!!
位置データもPythonで!!!
hide ogawa
【メタサーベイ】基盤モデル / Foundation Models
【メタサーベイ】基盤モデル / Foundation Models
cvpaper. challenge
DockerコンテナでGitを使う
DockerコンテナでGitを使う
Kazuhiro Suga
機械学習応用のためのソフトウェアエンジニアリングパターン
機械学習応用のためのソフトウェアエンジニアリングパターン
HironoriTAKEUCHI1
Ml system in_python
Ml system in_python
yusuke shibui
ChatGPT 人間のフィードバックから強化学習した対話AI
ChatGPT 人間のフィードバックから強化学習した対話AI
Shota Imai
SSII2019企画: 点群深層学習の研究動向
SSII2019企画: 点群深層学習の研究動向
SSII
画像認識モデルを作るための鉄板レシピ
画像認識モデルを作るための鉄板レシピ
Takahiro Kubo
Empfohlen
位置データもPythonで!!!
位置データもPythonで!!!
hide ogawa
【メタサーベイ】基盤モデル / Foundation Models
【メタサーベイ】基盤モデル / Foundation Models
cvpaper. challenge
DockerコンテナでGitを使う
DockerコンテナでGitを使う
Kazuhiro Suga
機械学習応用のためのソフトウェアエンジニアリングパターン
機械学習応用のためのソフトウェアエンジニアリングパターン
HironoriTAKEUCHI1
Ml system in_python
Ml system in_python
yusuke shibui
ChatGPT 人間のフィードバックから強化学習した対話AI
ChatGPT 人間のフィードバックから強化学習した対話AI
Shota Imai
SSII2019企画: 点群深層学習の研究動向
SSII2019企画: 点群深層学習の研究動向
SSII
画像認識モデルを作るための鉄板レシピ
画像認識モデルを作るための鉄板レシピ
Takahiro Kubo
MLOps に基づく AI/ML 実運用最前線 ~画像、動画データにおける MLOps 事例のご紹介~(映像情報メディア学会2021年冬季大会企画セッショ...
MLOps に基づく AI/ML 実運用最前線 ~画像、動画データにおける MLOps 事例のご紹介~(映像情報メディア学会2021年冬季大会企画セッショ...
NTT DATA Technology & Innovation
Swin Transformer (ICCV'21 Best Paper) を完璧に理解する資料
Swin Transformer (ICCV'21 Best Paper) を完璧に理解する資料
Yusuke Uchida
画像キャプションの自動生成
画像キャプションの自動生成
Yoshitaka Ushiku
ナレッジグラフ/LOD利用技術の入門(後編)
ナレッジグラフ/LOD利用技術の入門(後編)
KnowledgeGraph
グラフニューラルネットワーク入門
グラフニューラルネットワーク入門
ryosuke-kojima
backbone としての timm 入門
backbone としての timm 入門
Takuji Tahara
Tensorflow Liteの量子化アーキテクチャ
Tensorflow Liteの量子化アーキテクチャ
HitoshiSHINABE1
深層学習によるHuman Pose Estimationの基礎
深層学習によるHuman Pose Estimationの基礎
Takumi Ohkuma
ナレッジグラフとオントロジー
ナレッジグラフとオントロジー
University of Tsukuba
近年のHierarchical Vision Transformer
近年のHierarchical Vision Transformer
Yusuke Uchida
2018年01月27日 TensorBoardによる学習の可視化
2018年01月27日 TensorBoardによる学習の可視化
aitc_jp
[DL輪読会]BERT: Pre-training of Deep Bidirectional Transformers for Language Und...
[DL輪読会]BERT: Pre-training of Deep Bidirectional Transformers for Language Und...
Deep Learning JP
モデルではなく、データセットを蒸留する
モデルではなく、データセットを蒸留する
Takahiro Kubo
機械学習モデルの判断根拠の説明(Ver.2)
機械学習モデルの判断根拠の説明(Ver.2)
Satoshi Hara
[DL輪読会]Grokking: Generalization Beyond Overfitting on Small Algorithmic Datasets
[DL輪読会]Grokking: Generalization Beyond Overfitting on Small Algorithmic Datasets
Deep Learning JP
情報抽出入門 〜非構造化データを構造化させる技術〜
情報抽出入門 〜非構造化データを構造化させる技術〜
Yuya Unno
【DL輪読会】GPT-4Technical Report
【DL輪読会】GPT-4Technical Report
Deep Learning JP
畳み込みニューラルネットワークの高精度化と高速化
畳み込みニューラルネットワークの高精度化と高速化
Yusuke Uchida
Prophet入門【Python編】Facebookの時系列予測ツール
Prophet入門【Python編】Facebookの時系列予測ツール
hoxo_m
CatBoost on GPU のひみつ
CatBoost on GPU のひみつ
Takuji Tahara
211120 他人の書いたPythonスクリプトをステップ実行で理解する
211120 他人の書いたPythonスクリプトをステップ実行で理解する
Takuya Nishimoto
本気でPythonで宛名書きした話
本気でPythonで宛名書きした話
Satoshi Yamada
Weitere ähnliche Inhalte
Was ist angesagt?
MLOps に基づく AI/ML 実運用最前線 ~画像、動画データにおける MLOps 事例のご紹介~(映像情報メディア学会2021年冬季大会企画セッショ...
MLOps に基づく AI/ML 実運用最前線 ~画像、動画データにおける MLOps 事例のご紹介~(映像情報メディア学会2021年冬季大会企画セッショ...
NTT DATA Technology & Innovation
Swin Transformer (ICCV'21 Best Paper) を完璧に理解する資料
Swin Transformer (ICCV'21 Best Paper) を完璧に理解する資料
Yusuke Uchida
画像キャプションの自動生成
画像キャプションの自動生成
Yoshitaka Ushiku
ナレッジグラフ/LOD利用技術の入門(後編)
ナレッジグラフ/LOD利用技術の入門(後編)
KnowledgeGraph
グラフニューラルネットワーク入門
グラフニューラルネットワーク入門
ryosuke-kojima
backbone としての timm 入門
backbone としての timm 入門
Takuji Tahara
Tensorflow Liteの量子化アーキテクチャ
Tensorflow Liteの量子化アーキテクチャ
HitoshiSHINABE1
深層学習によるHuman Pose Estimationの基礎
深層学習によるHuman Pose Estimationの基礎
Takumi Ohkuma
ナレッジグラフとオントロジー
ナレッジグラフとオントロジー
University of Tsukuba
近年のHierarchical Vision Transformer
近年のHierarchical Vision Transformer
Yusuke Uchida
2018年01月27日 TensorBoardによる学習の可視化
2018年01月27日 TensorBoardによる学習の可視化
aitc_jp
[DL輪読会]BERT: Pre-training of Deep Bidirectional Transformers for Language Und...
[DL輪読会]BERT: Pre-training of Deep Bidirectional Transformers for Language Und...
Deep Learning JP
モデルではなく、データセットを蒸留する
モデルではなく、データセットを蒸留する
Takahiro Kubo
機械学習モデルの判断根拠の説明(Ver.2)
機械学習モデルの判断根拠の説明(Ver.2)
Satoshi Hara
[DL輪読会]Grokking: Generalization Beyond Overfitting on Small Algorithmic Datasets
[DL輪読会]Grokking: Generalization Beyond Overfitting on Small Algorithmic Datasets
Deep Learning JP
情報抽出入門 〜非構造化データを構造化させる技術〜
情報抽出入門 〜非構造化データを構造化させる技術〜
Yuya Unno
【DL輪読会】GPT-4Technical Report
【DL輪読会】GPT-4Technical Report
Deep Learning JP
畳み込みニューラルネットワークの高精度化と高速化
畳み込みニューラルネットワークの高精度化と高速化
Yusuke Uchida
Prophet入門【Python編】Facebookの時系列予測ツール
Prophet入門【Python編】Facebookの時系列予測ツール
hoxo_m
CatBoost on GPU のひみつ
CatBoost on GPU のひみつ
Takuji Tahara
Was ist angesagt?
(20)
MLOps に基づく AI/ML 実運用最前線 ~画像、動画データにおける MLOps 事例のご紹介~(映像情報メディア学会2021年冬季大会企画セッショ...
MLOps に基づく AI/ML 実運用最前線 ~画像、動画データにおける MLOps 事例のご紹介~(映像情報メディア学会2021年冬季大会企画セッショ...
Swin Transformer (ICCV'21 Best Paper) を完璧に理解する資料
Swin Transformer (ICCV'21 Best Paper) を完璧に理解する資料
画像キャプションの自動生成
画像キャプションの自動生成
ナレッジグラフ/LOD利用技術の入門(後編)
ナレッジグラフ/LOD利用技術の入門(後編)
グラフニューラルネットワーク入門
グラフニューラルネットワーク入門
backbone としての timm 入門
backbone としての timm 入門
Tensorflow Liteの量子化アーキテクチャ
Tensorflow Liteの量子化アーキテクチャ
深層学習によるHuman Pose Estimationの基礎
深層学習によるHuman Pose Estimationの基礎
ナレッジグラフとオントロジー
ナレッジグラフとオントロジー
近年のHierarchical Vision Transformer
近年のHierarchical Vision Transformer
2018年01月27日 TensorBoardによる学習の可視化
2018年01月27日 TensorBoardによる学習の可視化
[DL輪読会]BERT: Pre-training of Deep Bidirectional Transformers for Language Und...
[DL輪読会]BERT: Pre-training of Deep Bidirectional Transformers for Language Und...
モデルではなく、データセットを蒸留する
モデルではなく、データセットを蒸留する
機械学習モデルの判断根拠の説明(Ver.2)
機械学習モデルの判断根拠の説明(Ver.2)
[DL輪読会]Grokking: Generalization Beyond Overfitting on Small Algorithmic Datasets
[DL輪読会]Grokking: Generalization Beyond Overfitting on Small Algorithmic Datasets
情報抽出入門 〜非構造化データを構造化させる技術〜
情報抽出入門 〜非構造化データを構造化させる技術〜
【DL輪読会】GPT-4Technical Report
【DL輪読会】GPT-4Technical Report
畳み込みニューラルネットワークの高精度化と高速化
畳み込みニューラルネットワークの高精度化と高速化
Prophet入門【Python編】Facebookの時系列予測ツール
Prophet入門【Python編】Facebookの時系列予測ツール
CatBoost on GPU のひみつ
CatBoost on GPU のひみつ
Ähnlich wie 他人が書いたコードのリファレンスを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
Ähnlich wie 他人が書いたコードのリファレンスを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 )
Kürzlich hochgeladen
人的資本経営のための地理情報インテリジェンス 作業パターン分析と心身状態把握に関する実証事例
人的資本経営のための地理情報インテリジェンス 作業パターン分析と心身状態把握に関する実証事例
Kurata Takeshi
本の感想共有会「データモデリングでドメインを駆動する」本が突きつける我々の課題について
本の感想共有会「データモデリングでドメインを駆動する」本が突きつける我々の課題について
Masatsugu Matsushita
Linuxサーバー構築 学習のポイントと環境構築 OSC2024名古屋 セミナー資料
Linuxサーバー構築 学習のポイントと環境構築 OSC2024名古屋 セミナー資料
Toru Miyahara
【登壇資料】スタートアップCTO経験からキャリアについて再考する CTO・VPoEに聞く by DIGGLE CTO 水上
【登壇資料】スタートアップCTO経験からキャリアについて再考する CTO・VPoEに聞く by DIGGLE CTO 水上
mizukami4
今さら聞けない人のためのDevOps超入門 OSC2024名古屋 セミナー資料
今さら聞けない人のためのDevOps超入門 OSC2024名古屋 セミナー資料
Toru Miyahara
今年こそ始めたい!SQL超入門 セミナー資料 2024年5月22日 富士通クラウドミートアップ
今年こそ始めたい!SQL超入門 セミナー資料 2024年5月22日 富士通クラウドミートアップ
Toru Miyahara
Kürzlich hochgeladen
(6)
人的資本経営のための地理情報インテリジェンス 作業パターン分析と心身状態把握に関する実証事例
人的資本経営のための地理情報インテリジェンス 作業パターン分析と心身状態把握に関する実証事例
本の感想共有会「データモデリングでドメインを駆動する」本が突きつける我々の課題について
本の感想共有会「データモデリングでドメインを駆動する」本が突きつける我々の課題について
Linuxサーバー構築 学習のポイントと環境構築 OSC2024名古屋 セミナー資料
Linuxサーバー構築 学習のポイントと環境構築 OSC2024名古屋 セミナー資料
【登壇資料】スタートアップCTO経験からキャリアについて再考する CTO・VPoEに聞く by DIGGLE CTO 水上
【登壇資料】スタートアップCTO経験からキャリアについて再考する CTO・VPoEに聞く by DIGGLE CTO 水上
今さら聞けない人のためのDevOps超入門 OSC2024名古屋 セミナー資料
今さら聞けない人のためのDevOps超入門 OSC2024名古屋 セミナー資料
今年こそ始めたい!SQL超入門 セミナー資料 2024年5月22日 富士通クラウドミートアップ
今年こそ始めたい!SQL超入門 セミナー資料 2024年5月22日 富士通クラウドミートアップ
他人が書いたコードのリファレンスを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!
Hinweis der Redaktion
ご静聴ありがとうございました
Jetzt herunterladen