Enviar búsqueda
Cargar
他人が書いたコードのリファレンスをSphinxで作る方法
•
Descargar como PPTX, PDF
•
1 recomendación
•
2,260 vistas
T
Takeshi Sugiyama
Seguir
PyConJP2021 Day2
Leer menos
Leer más
Ingeniería
Denunciar
Compartir
Denunciar
Compartir
1 de 44
Descargar ahora
Recomendados
レコメンドアルゴリズムの基本と周辺知識と実装方法
レコメンドアルゴリズムの基本と周辺知識と実装方法
Takeshi Mikami
データマイニングの話詰め合わせ
データマイニングの話詰め合わせ
Tokoroten Nakayama
どうして昔の人は八進数でしゃべるのか?
どうして昔の人は八進数でしゃべるのか?
たけおか しょうぞう
PyCon2020 Pythonで競プロをしよう! 〜入門者が知っておくべき高速化Tips〜
PyCon2020 Pythonで競プロをしよう! 〜入門者が知っておくべき高速化Tips〜
Kosaku Ono
PythonとPyCoRAMでお手軽にFPGAシステムを開発してみよう
PythonとPyCoRAMでお手軽にFPGAシステムを開発してみよう
Shinya Takamaeda-Y
Optunaを使ったHuman-in-the-loop最適化の紹介 - 2023/04/27 W&B 東京ミートアップ #3
Optunaを使ったHuman-in-the-loop最適化の紹介 - 2023/04/27 W&B 東京ミートアップ #3
Preferred Networks
エンジニアから飛んでくるマサカリを受け止める心得
エンジニアから飛んでくるマサカリを受け止める心得
Reimi Kuramochi Chiba
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
Atsushi Nakada
Recomendados
レコメンドアルゴリズムの基本と周辺知識と実装方法
レコメンドアルゴリズムの基本と周辺知識と実装方法
Takeshi Mikami
データマイニングの話詰め合わせ
データマイニングの話詰め合わせ
Tokoroten Nakayama
どうして昔の人は八進数でしゃべるのか?
どうして昔の人は八進数でしゃべるのか?
たけおか しょうぞう
PyCon2020 Pythonで競プロをしよう! 〜入門者が知っておくべき高速化Tips〜
PyCon2020 Pythonで競プロをしよう! 〜入門者が知っておくべき高速化Tips〜
Kosaku Ono
PythonとPyCoRAMでお手軽にFPGAシステムを開発してみよう
PythonとPyCoRAMでお手軽にFPGAシステムを開発してみよう
Shinya Takamaeda-Y
Optunaを使ったHuman-in-the-loop最適化の紹介 - 2023/04/27 W&B 東京ミートアップ #3
Optunaを使ったHuman-in-the-loop最適化の紹介 - 2023/04/27 W&B 東京ミートアップ #3
Preferred Networks
エンジニアから飛んでくるマサカリを受け止める心得
エンジニアから飛んでくるマサカリを受け止める心得
Reimi Kuramochi Chiba
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
Atsushi Nakada
「速」を落とさないコードレビュー
「速」を落とさないコードレビュー
Takafumi ONAKA
WebRTCを利用した遠隔リアルタイム映像処理フレームワークの実装
WebRTCを利用した遠隔リアルタイム映像処理フレームワークの実装
tnoho
心理的安全性と、Veinの紹介 Psychological safety and introduction of Vein
心理的安全性と、Veinの紹介 Psychological safety and introduction of Vein
Tokoroten Nakayama
ChatGPT 人間のフィードバックから強化学習した対話AI
ChatGPT 人間のフィードバックから強化学習した対話AI
Shota Imai
ナレッジグラフとオントロジー
ナレッジグラフとオントロジー
University of Tsukuba
研究発表を準備する(2022年版)
研究発表を準備する(2022年版)
Takayuki Itoh
研究分野をサーベイする
研究分野をサーベイする
Takayuki Itoh
入門 Kubeflow ~Kubernetesで機械学習をはじめるために~ (NTT Tech Conference #4 講演資料)
入門 Kubeflow ~Kubernetesで機械学習をはじめるために~ (NTT Tech Conference #4 講演資料)
NTT DATA Technology & Innovation
PlaySQLAlchemy: SQLAlchemy入門
PlaySQLAlchemy: SQLAlchemy入門
泰 増田
ナレッジグラフ入門
ナレッジグラフ入門
KnowledgeGraph
ラボラトリーオートメーションのためのソフトウェア思想教育(非プログラマ―が知っておくべきプログラミングの本質)
ラボラトリーオートメーションのためのソフトウェア思想教育(非プログラマ―が知っておくべきプログラミングの本質)
Tokoroten Nakayama
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
Tokoroten Nakayama
マーブル図で怖くないRxJS
マーブル図で怖くないRxJS
bitbank, Inc. Tokyo, Japan
TDD のこころ
TDD のこころ
Takuto Wada
先端技術とメディア表現1 #FTMA15
先端技術とメディア表現1 #FTMA15
Yoichi Ochiai
IT系エンジニアのためのプレゼンテーション入門
IT系エンジニアのためのプレゼンテーション入門
Masahito Zembutsu
境界付けられたコンテキスト 概念編 (ドメイン駆動設計用語解説シリーズ)
境界付けられたコンテキスト 概念編 (ドメイン駆動設計用語解説シリーズ)
Koichiro Matsuoka
Tensor コアを使った PyTorch の高速化
Tensor コアを使った PyTorch の高速化
Yusuke Fujimoto
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
Kentaro Matsui
エキスパートPythonプログラミング改訂3版の読みどころ
エキスパートPythonプログラミング改訂3版の読みどころ
Takayuki Shimizukawa
211120 他人の書いたPythonスクリプトをステップ実行で理解する
211120 他人の書いたPythonスクリプトをステップ実行で理解する
Takuya Nishimoto
本気でPythonで宛名書きした話
本気でPythonで宛名書きした話
Satoshi Yamada
Más contenido relacionado
La actualidad más candente
「速」を落とさないコードレビュー
「速」を落とさないコードレビュー
Takafumi ONAKA
WebRTCを利用した遠隔リアルタイム映像処理フレームワークの実装
WebRTCを利用した遠隔リアルタイム映像処理フレームワークの実装
tnoho
心理的安全性と、Veinの紹介 Psychological safety and introduction of Vein
心理的安全性と、Veinの紹介 Psychological safety and introduction of Vein
Tokoroten Nakayama
ChatGPT 人間のフィードバックから強化学習した対話AI
ChatGPT 人間のフィードバックから強化学習した対話AI
Shota Imai
ナレッジグラフとオントロジー
ナレッジグラフとオントロジー
University of Tsukuba
研究発表を準備する(2022年版)
研究発表を準備する(2022年版)
Takayuki Itoh
研究分野をサーベイする
研究分野をサーベイする
Takayuki Itoh
入門 Kubeflow ~Kubernetesで機械学習をはじめるために~ (NTT Tech Conference #4 講演資料)
入門 Kubeflow ~Kubernetesで機械学習をはじめるために~ (NTT Tech Conference #4 講演資料)
NTT DATA Technology & Innovation
PlaySQLAlchemy: SQLAlchemy入門
PlaySQLAlchemy: SQLAlchemy入門
泰 増田
ナレッジグラフ入門
ナレッジグラフ入門
KnowledgeGraph
ラボラトリーオートメーションのためのソフトウェア思想教育(非プログラマ―が知っておくべきプログラミングの本質)
ラボラトリーオートメーションのためのソフトウェア思想教育(非プログラマ―が知っておくべきプログラミングの本質)
Tokoroten Nakayama
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
Tokoroten Nakayama
マーブル図で怖くないRxJS
マーブル図で怖くないRxJS
bitbank, Inc. Tokyo, Japan
TDD のこころ
TDD のこころ
Takuto Wada
先端技術とメディア表現1 #FTMA15
先端技術とメディア表現1 #FTMA15
Yoichi Ochiai
IT系エンジニアのためのプレゼンテーション入門
IT系エンジニアのためのプレゼンテーション入門
Masahito Zembutsu
境界付けられたコンテキスト 概念編 (ドメイン駆動設計用語解説シリーズ)
境界付けられたコンテキスト 概念編 (ドメイン駆動設計用語解説シリーズ)
Koichiro Matsuoka
Tensor コアを使った PyTorch の高速化
Tensor コアを使った PyTorch の高速化
Yusuke Fujimoto
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
Kentaro Matsui
エキスパートPythonプログラミング改訂3版の読みどころ
エキスパートPythonプログラミング改訂3版の読みどころ
Takayuki Shimizukawa
La actualidad más candente
(20)
「速」を落とさないコードレビュー
「速」を落とさないコードレビュー
WebRTCを利用した遠隔リアルタイム映像処理フレームワークの実装
WebRTCを利用した遠隔リアルタイム映像処理フレームワークの実装
心理的安全性と、Veinの紹介 Psychological safety and introduction of Vein
心理的安全性と、Veinの紹介 Psychological safety and introduction of Vein
ChatGPT 人間のフィードバックから強化学習した対話AI
ChatGPT 人間のフィードバックから強化学習した対話AI
ナレッジグラフとオントロジー
ナレッジグラフとオントロジー
研究発表を準備する(2022年版)
研究発表を準備する(2022年版)
研究分野をサーベイする
研究分野をサーベイする
入門 Kubeflow ~Kubernetesで機械学習をはじめるために~ (NTT Tech Conference #4 講演資料)
入門 Kubeflow ~Kubernetesで機械学習をはじめるために~ (NTT Tech Conference #4 講演資料)
PlaySQLAlchemy: SQLAlchemy入門
PlaySQLAlchemy: SQLAlchemy入門
ナレッジグラフ入門
ナレッジグラフ入門
ラボラトリーオートメーションのためのソフトウェア思想教育(非プログラマ―が知っておくべきプログラミングの本質)
ラボラトリーオートメーションのためのソフトウェア思想教育(非プログラマ―が知っておくべきプログラミングの本質)
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
マーブル図で怖くないRxJS
マーブル図で怖くないRxJS
TDD のこころ
TDD のこころ
先端技術とメディア表現1 #FTMA15
先端技術とメディア表現1 #FTMA15
IT系エンジニアのためのプレゼンテーション入門
IT系エンジニアのためのプレゼンテーション入門
境界付けられたコンテキスト 概念編 (ドメイン駆動設計用語解説シリーズ)
境界付けられたコンテキスト 概念編 (ドメイン駆動設計用語解説シリーズ)
Tensor コアを使った PyTorch の高速化
Tensor コアを使った PyTorch の高速化
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
エキスパートPythonプログラミング改訂3版の読みどころ
エキスパートPythonプログラミング改訂3版の読みどころ
Similar a 他人が書いたコードのリファレンスを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 a 他人が書いたコードのリファレンスを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 )
Último
Linuxサーバー構築 学習のポイントと環境構築 OSC2024名古屋 セミナー資料
Linuxサーバー構築 学習のポイントと環境構築 OSC2024名古屋 セミナー資料
Toru Miyahara
本の感想共有会「データモデリングでドメインを駆動する」本が突きつける我々の課題について
本の感想共有会「データモデリングでドメインを駆動する」本が突きつける我々の課題について
Masatsugu Matsushita
今年こそ始めたい!SQL超入門 セミナー資料 2024年5月22日 富士通クラウドミートアップ
今年こそ始めたい!SQL超入門 セミナー資料 2024年5月22日 富士通クラウドミートアップ
Toru Miyahara
【登壇資料】スタートアップCTO経験からキャリアについて再考する CTO・VPoEに聞く by DIGGLE CTO 水上
【登壇資料】スタートアップCTO経験からキャリアについて再考する CTO・VPoEに聞く by DIGGLE CTO 水上
mizukami4
人的資本経営のための地理情報インテリジェンス 作業パターン分析と心身状態把握に関する実証事例
人的資本経営のための地理情報インテリジェンス 作業パターン分析と心身状態把握に関する実証事例
Kurata Takeshi
今さら聞けない人のためのDevOps超入門 OSC2024名古屋 セミナー資料
今さら聞けない人のためのDevOps超入門 OSC2024名古屋 セミナー資料
Toru Miyahara
Último
(6)
Linuxサーバー構築 学習のポイントと環境構築 OSC2024名古屋 セミナー資料
Linuxサーバー構築 学習のポイントと環境構築 OSC2024名古屋 セミナー資料
本の感想共有会「データモデリングでドメインを駆動する」本が突きつける我々の課題について
本の感想共有会「データモデリングでドメインを駆動する」本が突きつける我々の課題について
今年こそ始めたい!SQL超入門 セミナー資料 2024年5月22日 富士通クラウドミートアップ
今年こそ始めたい!SQL超入門 セミナー資料 2024年5月22日 富士通クラウドミートアップ
【登壇資料】スタートアップCTO経験からキャリアについて再考する CTO・VPoEに聞く by DIGGLE CTO 水上
【登壇資料】スタートアップCTO経験からキャリアについて再考する CTO・VPoEに聞く by DIGGLE CTO 水上
人的資本経営のための地理情報インテリジェンス 作業パターン分析と心身状態把握に関する実証事例
人的資本経営のための地理情報インテリジェンス 作業パターン分析と心身状態把握に関する実証事例
今さら聞けない人のためのDevOps超入門 OSC2024名古屋 セミナー資料
今さら聞けない人のためのDevOps超入門 OSC2024名古屋 セミナー資料
他人が書いたコードのリファレンスを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!
Notas del editor
ご静聴ありがとうございました
Descargar ahora