Sphinx 社内勉強会
49
sphinx社内勉強会 “このような、プログラマーが ドキュメントを書きたくなってしまう すばらしいツールに乾杯！” ユーザーの声: 2011/11/18 t2y 2011年11月18日金曜日
-
Upload
tetsuya-morimoto -
Category
Technology
-
view
4.850 -
download
3
description
Sphinx がどういうものかをざっくり紹介した勉強会の資料です
Transcript of Sphinx 社内勉強会
sphinx社内勉強会“このような、プログラマーがドキュメントを書きたくなってしまうすばらしいツールに乾杯！”
ユーザーの声:
2011/11/18 t2y
2011年11月18日金曜日
お前、誰よ森本 哲也 (もりもと てつや)
Pythonプログラミングが好きです
Twitter: @t2y (日本語) , @t2y_en (英語)
G+: gplus.to/t2y (英語メイン)
Hatena:
forest book (主にプログラミング、技術ネタ)
forest nook (普通の日記)
2011年11月18日金曜日
エキスパートpythonプログラミングpython中級本
構文ベストプラクティス
良い名前付け
パッケージング
ドキュメント
テスト駆動開発
最適化
デザインパターン
10章: プロジェクトのドキュメント作成
sphinxの紹介
pythonにおけるアプリケーション開発
第4刷
2011年11月18日金曜日
目次sphinx概要
rest概要
ドキュメンテーション
sphinxを拡張するツール
sphinxとpythonパッケージ
sphinxでリファレンスを書く
2011年11月18日金曜日
sphinx概要(1)
もともとの目的
pythonドキュメントを作成するため
開発者Georg Brandl
pocooの開発リーダーの1人
2005年からpythonコア開発者
python3リリースマネージャー
"Pocoo ispronounced /ˈpokʉː/"
2011年11月18日金曜日
sphinx概要(2)
構成
sphinx: ドキュメントビルダー
docutils: RESTパーサー
pygments: コードハイライト
jinja2: HTMLテンプレートエンジン
doxygen のようなものらしいです
2011年11月18日金曜日
sphinx概要(3)
ドキュメントビルダーって？
latexの親戚、モダンなlatex
makefileでドキュメントをビルド
restのテキストからフォーマット変換
国際化対応(gettext)
2011年11月18日金曜日
変換できるフォーマット$ make help
Please use `make <target>' where <target> is one of
html to make standalone HTML files
dirhtml to make HTML files called index.html in directories
singlehtml to make one big HTML file
text to make text files
man to make manual pages
pickle to make pickle files
json to make json files
htmlhelp to make HTML files and a HTML help project
qthelp to make Qt help files and project
devhelp to make Devhelp files and project
epub to make an epub file
latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
latexpdf to make LaTeX files and run pdflatex
texinfo to make Texinfo files
info to make Texinfo files and run them through makeinfo
gettext to make PO message catalogs
changes to make an overview over all changed/added/deprecated items
linkcheck to check all external links for integrity
djangoドキュメントjsonからレンダリング
2011年11月18日金曜日
sphinx概要(4)拡張性の高さ
ビルダー
doc/xlsビルダーを作るとヒーロー？
restディレクティブやマークアップ
blockdiag:ブロック図生成
ビルドプロセスのフック
リンクやスペルチェック
.. blockdiag:: { A [label="自分"];
A -> B [label="Open"]; A -> C; O -> P -> C; }
2011年11月18日金曜日
sphinx概要(5)sphinxを利用しているサイト
python系
pythonドキュメント
sqlalchemyドキュメント
それ以外のコミュニティでも利用されてる
groongaドキュメント
symfony2ドキュメント
2011年11月18日金曜日
sphinx概要(6)
日本コミュニティの充実sphinx-users.jp
sphinxドキュメントの日本語翻訳
sphinx全般のハブサイト
会長: 渋川さん 副会長: 清水川さん
2011年11月18日金曜日
目次sphinx概要
rest概要
ドキュメンテーション
sphinxを拡張するツール
sphinxとpythonパッケージ
sphinxでリファレンスを書く
2011年11月18日金曜日
rest概要
WIKIに良く似た記法
STRUCTUREDTEXTのインデントを除去して拡張
PYTHONコード内にドキュメントを埋め込む用途
リファレンス
reStructuredText入門
2011年11月18日金曜日
restを書いてみる
デモ: 実際に書いてみる
2011年11月18日金曜日
sphinxを使う
デモ: sphinxでrestのテキストをビルドする
2011年11月18日金曜日
目次sphinx概要
rest概要
ドキュメンテーション
sphinxを拡張するツール
sphinxとpythonパッケージ
sphinxでリファレンスを書く
2011年11月18日金曜日
ドキュメンテーション
ドキュメント作成って？
地味: 分かりやすい文章を書く
地道: 常に更新していく
地盤: 情報共有の基本、様々なフォーマット
もう少し楽しくドキュメントを作成しよう
おもしろそうなイメージがない
2011年11月18日金曜日
ドキュメントを書くコツ2つのステップで書く
読者のターゲットを明確にする
シンプルなスタイルを使用する
情報のスコープを絞る
実在するようなコードのサンプルを使用する
なるべく少なく、かつ十分なドキュメント
テンプレートの使用
10章: プロジェクトのドキュメント作成
sphinxの紹介
2011年11月18日金曜日
ドキュメントが煩わしいというのは
ドキュメントの書き方が分からない
何を？誰に？どのぐらいのレベルで？書くの？
ドキュメントの本質じゃないことが煩わしい
構造化(階層化)
バージョン管理
フォーマット変換
2011年11月18日金曜日
そこでsphinxですよ！
2011年11月18日金曜日
ドキュメントを書く良い動機付け
プログラマーがドキュメントを書きたくなるって？
restでシンプルに構造化できる
テキストで書ける => バージョン管理できる
コード内にドキュメントが書ける => 更新が容易
html/epub/pdfの変換 => 必要十分
2011年11月18日金曜日
目次sphinx概要
rest概要
ドキュメンテーション
sphinxを拡張するツール
sphinxとpythonパッケージ
sphinxでリファレンスを書く
2011年11月18日金曜日
sphinxを拡張するツール
拡張パッケージ
pypiをsphinxcontribで検索
30個以上はある
pypiをsphinxjpで検索
8個ある
2011年11月18日金曜日
sphinxcontrib.spelling
sphinxcontrib.spelling
doug hellmannが開発
pyenchantライブラリによるスペルチェック
sphinxのビルドオプションとして実行
2011年11月18日金曜日
sphinxjp.themes.s6
sphinxjp.themes.s6
新婚の清水川さんが開発
restでプレゼンテーション
s6というjsのプレゼンツールを組み込む
s6向けのテーマ(テンプレートやcss)を提供
“..s6:: xxx”ディレクティブの拡張
2011年11月18日金曜日
blockdiag
blockdiag
通称「世界の小宮」さんが開発
ブロック図を描くツール
diagシリーズが好評seqdiag
actdiag
nwdiag
rackdiag
インタラクティブシェルで遊ぼう
2011年11月18日金曜日
sphinxjp.shibukawa
sphinxjp.shibukawa
通称「世界の小宮」さんが開発
渋川さんへのバースデーパッケージらしい
こんな感じで盛り上がってるみたい、、、です
2011年11月18日金曜日
目次sphinx概要
rest概要
ドキュメンテーション
sphinxを拡張するツール
sphinxとpythonパッケージ
sphinxでリファレンスを書く
2011年11月18日金曜日
docstring
sphinxのもともとの目的って？
pythonドキュメントを作るためのツール
コード内のコメントからドキュメントを生成
コード内のコメントをdocstringと呼ぶ
2011年11月18日金曜日
sphinxとpythonパッケージング
pythonパッケージングをしたことある方？
2011年11月18日金曜日
pythonパッケージングsetup.pyを定義
ここでは以下のツールを使う
python標準ライブラリ: distutils
distutilsの拡張ライブラリ: distribute
参考:
清水川web: distutils, setuptools, distribute, pip, virtualenv, buildout
2011年11月18日金曜日
apiドキュメント生成
e.g) flask
$ cd flask_repository
$ python setup.py build_sphinx
build/sphinx/html にドキュメントを生成
時間があったら過去に作ったドキュメントを紹介
javadocのようなもの？
2011年11月18日金曜日
目次sphinx概要
rest概要
ドキュメンテーション
sphinxを拡張するツール
sphinxとpythonパッケージ
sphinxでリファレンスを書く
2011年11月18日金曜日
リファレンスを書こう
先週のpypy勉強会で、みなさんは既に自分の言語処理系を開発されたはずなので、好きなだけリファレンスドキュメントを書いてください
2011年11月18日金曜日
世の中にあるリファレンスを見てみよう
世の中にあるドキュメントを見てみる
pythonプロジェクト
djangoプロジェクト
pyramidプロジェクト
試しにビルドしてみる
2011年11月18日金曜日
ビルドの待ち時間に
世の中にあるドキュメントを見てみる
pythonプロジェクト
djangoプロジェクト
pyramidプロジェクト
webページに行ってみる
2011年11月18日金曜日
世の中にあるリファレンスを見てみよう
世の中にあるドキュメントを見てみる
pythonプロジェクト (v2.7.2)
ライブラリリファレンス
C/APIリファレンス
言語リファレンス
djangoプロジェクト(v1.3)
pyramidプロジェクト(v1.2)
実際にビルドしてみた
1424 page
192 page
122 page
1129 page
670 page
2011年11月18日金曜日
python書籍learning python (邦題: 初めてのpython)
著者: Mark Lutz
第1版(1999/4) ・・・ 384 page
第2版(2003/12) ・・・ 624 page
第3版(2007/10) ・・・ 752 page
第4版(2009/9) ・・・ 1216 page
2011年11月18日金曜日
他のpython書籍programming python (邦題: プログラミングpython)
著者: Mark Lutz
第1版(1996/10) ・・・ 902 page
第2版(2001/3) ・・・ 1296 page
第3版(2006/8) ・・・ 1600 page
第4版(2010/12) ・・・ 1632 page
2011年11月18日金曜日
ちょっと言いたい
Mark Lutz自重しろ
邦訳は追随してない
“python本は分厚いからねぇ”
pythonはシンプルだから初心者に優しいはず
初心者が1000ページもドキュメント読めるか！
ある編集者さんの声
2011年11月18日金曜日
目次sphinx概要
rest概要
ドキュメンテーション
sphinxを拡張するツール
sphinxとpythonパッケージ
sphinxでリファレンスを書く
2011年11月18日金曜日
雑談
技術的なお話ではないけれど、、、
sphinxでドキュメントを翻訳するお話
エキスパートpythonプログラミング本pymotw & python insider
ikazuchi
2011年11月18日金曜日
雑談目次
sphinxと翻訳
ikazuchiの翻訳
2011年11月18日金曜日
sphinxと翻訳
エキスパート Python プログラミングに学ぶ
PyMOTW 翻訳の進め方
Python Insider の国際化対応
興味ある方はブログを読んでみてください
2011年11月18日金曜日
ikazuchiの翻訳
PyPIをikazuchiで検索するikazuchi
CUIの翻訳ツールgoogle translate api
microsoft translate API
プラガブルな設計
2011年11月18日金曜日
ikazuchiデモちょっとikazuchiを使ってみましょう
もともとは自分のための翻訳補助ツール
PyPIにアップロードするテストパッケージ
pythonの名前空間パッケージの調査
europythonでのltネタ
(sphinxcontrib-ikazuchiを作る予定だった)
2011年11月18日金曜日
sphinxを拡張するならみなさんは開発者なのでsphinxの拡張や開発に興味をもったと思います、こんなことやるとコミュニティで喜ばれます
国際化対応(gettext)の改善
quickstartスクリプトの改善
ビルダー開発(doc/xlsとか)
2011年11月18日金曜日
まとめ
身近なものからrestで書こう
身近なものからsphinx拡張を開発してみよう
2011年11月18日金曜日
happy documenting with sphinx
2011年11月18日金曜日
