Sphinxを使って

本を書こう

2012/9/16PyCon JP 2012

http://清水川.jp/ @shimizukawa

● 株式会社BeProud所属● エキスパートPythonプログラミング

の翻訳(4名で)● Sphinx-users.jp 副会長● PyConJP 2011,2012 副座長

おまえ誰よ (a.k.a. 自己紹介)

● 秀和システム刊● B5変(430ページ)● 2940円● 2012年3月27日(火)

#pypro

Pythonプロフェッショナル

プログラミング

担当編集さんがPyConJPに販売に来てくれましたが、みんな持ってたとか・・・

おかげさまで売れてるみたいです

● BPStyle:

BPが実践で培ってきた、仕事でのPythonの

ノウハウを伝える本

● BP新人向け:

新しい会社のメンバーに早く仕事に慣れてもらうための本

本のコンセプト

4部構成

1. Pythonで開発しよう2. チーム開発のサイクル3. サービス公開4. 開発を加速するテクニック

目次

第1章：Pythonを始めよう第2章：Webアプリケーションを作る

Appendix A: VirtualBoxのセットアップ

Appendix B: OS(Ubuntu)のセットアップ

第1部：Pythonで開発しよう

第3章：チームの開発環境を整える第4章：ドキュメントの基盤を整える第5章：課題管理とレビュー第6章：モジュール分割設計と単体テスト第7章：パッケージングと環境セットアップの自動化第8章：Mercurialによるソースコード管理第9章：Jenkinsで継続的インテグレーション

第2部：チーム開発のサイクル

第10章：環境構築とデプロイの自動化第11章：アプリケーションのパフォーマンス改善第12章：Google App Engine

第13章：テストを味方にする第14章：Djangoを便利に使う第15章：便利なPythonモジュールを使おう

第3部：サービス公開

第4部：開発を加速するテクニック

1. tell-k: 1章, 12章,

AppendiA,B2. 岡野: 2章, 8章, 11章,

15章3. aita: 3章

4. 清水川: 4章, 7章

5. 今川館: 5章, 9章

6. 東: 5章, 10章

執筆者一覧

7. 冨田: 5章

8. (あお): 6章

9. 文殊堂: 8章

10. cactusman: 9章

11. drillbits: 1章, 12章

12. ナツ: 13章

13. 池田: 14章

14. 畠: 14章

● Sphinx = ドキュメンテーションツールhttp://sphinx-users.jp/

この本の原稿はSphinxで書きました

初回:$ hg clone [bpbookのリポジトリ] bpbook

$ cd bpbook$ python bootstrap.py$ bin/buildout

HTML生成:

$ vim 04.rst$ make html

Sphinx執筆環境構築を自動構築

Sphinxの変換の仕組み

reST(reStrucutrdText)を用意

docutilsノードツリーに変換

HTML等に変換

● 執筆はreST● 社内レビューはHTML● 社外レビューはPDF

目的別に異なるフォーマットで閲覧。

見た目を変えると、気づかなかった誤記やおかしな表現などに気づけるようになる。

執筆とレビュー

● [編集さん -> 印刷]たぶんInDesignか何か

● [執筆者 -> 編集さん]秀和システムさんのフォーマット

原稿の提出フォーマット

■■■■■Chapter 1 Pythonをはじめよう

▽◆・Pythonのセットアップ・Mercurialのセットアップ△◆

■■■■01-01 Pythonのセットアップ

● 原稿はSphinx(reST)で書いた

● 提出用フォーマットは書式が違う

● 提出フォーマットで初めから書くのは厳しい

● どうする？

提出用に手動で書き直す？

● 秀和システムさんの原稿フォーマットを出力しました

Sphinxの秀和ビルダーを作った

秀和システム提出原稿生成:

$ make syuwa

これだけ。

$ ls _build/syuwa01.txt 02.txt 03.txt 04.txt ....

提出原稿をSphinxから生成

● ビルダー作成に時間がかかってしまった● でも、刺身たんぽぽ作業はツライ● 今後3,4回くらい提出するから元は取れる！

戻ってきた校正原稿差分をreSTに戻すのに、また2日かかってしまった(´；ω;｀ )

3回目以降は書籍PDFに注釈で提出(´；ω;｀ )

秀和ビルダー作るのに丸2日以上

うまくいかなかったこと● 提出原稿の自動生成は明確な仕様が必要● 戻り原稿の受け取り方も考えておこう

うまくいったこと● 編集と差分管理しやすいテキストで書く● レビューは別のビューで行う● (Sphinx等)環境用意は自動化しておく● いつでも最新のHTML, PDFを提供する

○ →リポジトリコミット→Jenkinsでmake

まとめ