English version is here: https://www.slideshare.net/shimizukawa/writing-a-book-using-sphinx-sphinxconjp-2012 私の過去2冊の翻訳・執筆した本の経験から、Sphinxを活用して執筆環境を自動化したときの手順とそのメリットなどを紹介します。 発表時の動画はこちら: http://www.youtube.com/watch?v=7VOJpFHnPWg

1. Sphinxを使って
本を書こう
2012/9/16
PyCon JP 2012

2. おまえ誰よ (a.k.a. 自己紹介)
http://清水川.jp/ @shimizukawa
● 株式会社BeProud所属
● エキスパートPythonプログラミング
の翻訳(4名で)
● Sphinx-users.jp 副会長
● PyConJP 2011,2012 副座長

3. Pythonプロフェッショナル
プログラミング
● 秀和システム刊
● B5変(430ページ)
● 2940円
● 2012年3月27日(火)
#pypro

4. おかげさまで売れてるみたいです
担当編集さんがPyConJPに販売に来てくれまし
たが、みんな持ってたとか・・・

5. 本のコンセプト
● BPStyle:
BPが実践で培ってきた、仕事でのPythonの
ノウハウを伝える本
● BP新人向け:
新しい会社のメンバーに早く仕事に慣れても
らうための本

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

7. 第1部：Pythonで開発しよう
第1章：Pythonを始めよう
第2章：Webアプリケーションを作る
Appendix A: VirtualBoxのセットアップ
Appendix B: OS(Ubuntu)のセットアップ

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

9. 第3部：サービス公開
第10章：環境構築とデプロイの自動化
第11章：アプリケーションのパフォーマンス改善
第12章：Google App Engine
第4部：開発を加速するテクニック
第13章：テストを味方にする
第14章：Djangoを便利に使う
第15章：便利なPythonモジュールを使おう

10. 執筆者一覧
1. tell-k: 1章, 12章, 7. 冨田: 5章
AppendiA,B 8. (あお): 6章
2. 岡野: 2章, 8章, 11章, 9. 文殊堂: 8章
15章 10. cactusman: 9章
3. aita: 3章 11. drillbits: 1章, 12章
4. 清水川: 4章, 7章 12. ナツ: 13章
5. 今川館: 5章, 9章 13. 池田: 14章
6. 東: 5章, 10章 14. 畠: 14章

11. この本の原稿はSphinxで書きました
● Sphinx = ドキュメンテーションツール
http://sphinx-users.jp/

12. Sphinx執筆環境構築を自動構築
初回:
$ hg clone [bpbookのリポジトリ] bpbook
$ cd bpbook
$ python bootstrap.py
$ bin/buildout
HTML生成:
$ vim 04.rst
$ make html

13. Sphinxの変換の仕組み
reST(reStrucutrdText)を用意
docutilsノードツリーに変換
HTML等に変換

14. 執筆とレビュー
● 執筆はreST
● 社内レビューはHTML
● 社外レビューはPDF
目的別に異なるフォーマットで閲覧。
見た目を変えると、気づかなかった誤記やおか
しな表現などに気づけるようになる。

15. 原稿の提出フォーマット
● [編集さん -> 印刷]
たぶんInDesignか何か
● [執筆者 -> 編集さん]
秀和システムさんのフォーマット
■■■■■Chapter 1 Pythonをはじめよう
▽◆
・Pythonのセットアップ
・Mercurialのセットアップ
△◆
■■■■01-01 Pythonのセットアップ

16. 提出用に手動で書き直す？
● 原稿はSphinx(reST)で書いた
● 提出用フォーマットは書式が違う
● 提出フォーマットで初めから書くのは厳しい
● どうする？

17. Sphinxの秀和ビルダーを作った
● 秀和システムさんの原稿フォーマットを出力し
ました

18. 提出原稿をSphinxから生成
秀和システム提出原稿生成:
$ make syuwa
これだけ。
$ ls _build/syuwa
01.txt 02.txt 03.txt 04.txt ....

19. 秀和ビルダー作るのに丸2日以上
● ビルダー作成に時間がかかってしまった
● でも、刺身たんぽぽ作業はツライ
● 今後3,4回くらい提出するから元は取れる！
戻ってきた校正原稿差分をreSTに戻すのに、ま
た2日かかってしまった(´；ω;｀ )
3回目以降は書籍PDFに注釈で提出(´；ω;｀ )

20. まとめ
うまくいかなかったこと
● 提出原稿の自動生成は明確な仕様が必要
● 戻り原稿の受け取り方も考えておこう
うまくいったこと
● 編集と差分管理しやすいテキストで書く
● レビューは別のビューで行う
● (Sphinx等)環境用意は自動化しておく
● いつでも最新のHTML, PDFを提供する
○ →リポジトリコミット→Jenkinsでmake