Transcript

• 1. Sphinx-users.jp & Sphinxコミッター 清水川貴之
• 2. 自己紹介： 清水川貴之 @shimizukawa  株式会社BeProud所属  Sphinxコミッター  Sphinx-users.jp お財布担当  一般社団法人PyConJP理事  Pepper レンタル中
• 3. Sphinxで執筆した書籍1 エキスパートPythonプログラミング 2010, アスキー・メディアワークス刊  翻訳者4名  Sphinxを使って書いた日本 初の書籍（たぶん）  reSTで提出して、アスキー さんがEWBにがんばって変 換  校正戻し以降は執筆側で両 方メンテナンス地獄
• 4. エキPyシステム PDFからコピペ ＆Sphinxに整形 SCM (Bazzar) reST 校正 reST -> -> make html 執筆 確認 レビュー Spreadsheetでレビュー指摘
• 5. エキPyシステム PDFからコピペ ＆Sphinxに整形 SCM (Bazzar) 出版 翻訳 校正 レビュー Spreadsheetでレビュー指摘
• 6. Sphinxで執筆した書籍2 Pythonプロフェッショナルプログラミング  執筆者14名  make shuwa で、Sphinxから 直接提出用フォーマットで 出力  人数多くてマークアップや 文体を揃えるのが大変  校正戻し以降は執筆側で両 方メンテナンス地獄 2012, 秀和システム刊
• 7. PyProシステム Sphinxの雛形作成 SCM (Mercurial) reST make html 執筆 確認 レビュー 通知 Spreadsheetでレビュー指摘
• 8. PyProシステム Sphinxの雛形作成校正 make shuwa SCM (Mercurial) reST make html 執筆 確認 レビュー 通知 Spreadsheetでレビュー指摘
• 9. PyProシステム 校正 SCM (Mercurial) 執筆 レビュー 出版 Spreadsheetでレビュー指摘
• 10. Sphinxで執筆した書籍3 Sphinxをはじめよう（電子書籍） 2013, オライリー・ジャパン刊  執筆者4名  オライリーさんがmake xml からのRe:VIEW変換  リポジトリ直接校正のため、 戻しがなくて平和
• 11. レビュー Sphinxをはじめようシステム Sphinxの雛形作成 SCM (Bitbucket) reST make html 執筆 確認 Spreadsheetでレビュー指摘
• 12. レビュー Sphinxをはじめようシステム Sphinxの雛形作成 SCM (Bitbucket) reST make html 執筆 確認 出版 reST Re:VIEW 校正 make xml Spreadsheetでレビュー指摘
• 13. Sphinxで執筆中の書籍4 <- New!! Pythonプロフェッショナルプログラミング 第2版  執筆者11名  make shuwa で、Sphinxから 直接提出用フォーマットで 出力 2015, 秀和システム刊（予定）  初版の原稿をreSTに戻して なかったのを反映  校正戻し以降は…どうな る？（そろそろ考える）
• 14. PyPro第2版システム 前回のSphinx原稿 SCM (Mercurial) reST make html 執筆 確認 レビュー 通知 通知 Spreadsheetでレビュー指摘
• 15. PyPro第2版システム 前回のSphinx原稿 SCM (Mercurial) reST make html 執筆 確認 レビュー 通知 make shuwa Spreadsheetでレビュー指摘 校正 差分をもらう予定 通知
• 16. PyPro第2版(2014/9 ~ 2015/02)
• 17. PyPro第2版システム 前回のSphinx原稿 SCM (Mercurial) reST make html 執筆 確認 レビュー 通知 make shuwa Spreadsheetでレビュー指摘 校正 差分をもらう予定 通知
• 18. 中央リポジトリ 中央リポジトリ  Sphinx原稿管理  Push受付  Redmine の関連チケットにcommit表示  Jenkinsへ通知、ビルド  Slackへ通知SCM(Mercurial) チケット更新 reST 通知 ビルド
• 19. 執筆の工程 1. 私: Sphinx用に初期のディレクトリ構成を作る 2. 私: 社内のMercurialリポジトリにpush 3. 担当者: hg pull 4. 担当者: pip install –r req.txt (初回) 5. 担当者: 各章をそれぞれ執筆(reST) 6. 担当者: 手元でmake html 7. 担当者: ブラウザで自己レビュー 8. 担当者: hg push 9. 担当者: Jenkinsでエラー-> 修正 10. 担当者: レビュー通知-> 修正 前回の Sphinx原稿 レビュー指摘 ① ② ③ ⑤ ④ ⑦ ⑥ ⑧ ⑨ ⑩
• 20. Redmine Redmine  進捗管理  チケット更新-> Slack通知, メール通知  リポジトリ更新検知-> チケット更新 SCM (Mercurial)
• 21. Jenkins  ビルド管理  リポジトリ更新検知  hg pull  pip install –r requirements.txt  make html pdf  ビルド成功  Slack通知  成果物を提供  ビルド失敗  Slack通知 SCM レビュー 通知 PDF生成には、 TeXLive2014が必要。 各執筆者は環境を 持っていない。 TeXLive2014入り
• 22. Google Spreadsheet  レビュー指摘  Redmine等のチケットはあえて使わなかった  レビュアーにとって、チケットは重い（気がする）  Spreadsheetの長所、短所  他の人のレビュー状況がなんとなく分かる  さくさく書ける、緩い感じがして気軽  新しく指摘された部分が分からない 通知はGASを書いて Slackに更新通知。 差分は分からない。
• 23. 出版社への提出工程(2012) 1. 私: hg pull 2. 私: make shuwa 3. 私: tar zcf bpbook20141205.tgz shuwa 4. 私: cp bpbook20141205.tgz ~/Dropbox 5. 私: メールで連絡 make shuwa 校正 ① ②③ ④ ⑤
• 24. 執筆者 執筆はreST、執筆者レビューはHTML レビュー指摘はRedmine、または直接編集
• 25. 社内レビュー＆早期レビュー 社内レビューはHTML or LaTeX PDF レビュー指摘はGoogle Spreadsheet
• 26. 社外レビュー 出版形式PDF（希望者にはHTML渡し） レビュー指摘はGoogle Spreadsheet
• 27. 各フォーマットの比較 reStructuredText HTML LaTeX -> PDF 秀和システム原稿フォーマット
• 28. SphinxのＨＴＭＬ出力
• 29. SphinxのPDF出力
• 30. 秀和システム原稿フォーマット&出力 秀和システム原稿フォーマット出版用PDF出力
• 31. ここで改めて
• 32. Sphinx誕生: 2007年 作者: Georg Brandl 2007年にSphinxを開発  それまでLaTeXで作っていたPythonドキュメントが 複雑すぎてメンテ不能に。 簡単に扱えるツールが必要だった DocutilsのreStrucutredTextをベースに  reSTは、2002年にPythonのテキストマークアップとし て 採用されていた(PEP287) その他のコミッター Roland, @shimizukawa, @tk0miya
• 33. Docutils/reStructuredTextの特徴  ￥や｛ ｝ で目がチカチカしない  レイアウト制御命令がない  レイアウトを意識せずに内容に集中できる  テキストのままでも読みやすい  一部のマークアップを拡張可能(role, directive) :idx: ロールを追加blockdiag directiveを追加→ 出力
• 34. Sphinxの特徴  Docutilsは単ページのみ。Sphinxは複数ページを扱 う。  全てのページをツリー構造に繋ぐtoctree  複数のページを縦横に繋ぐ参照  各種フォーマットの出力  HTML, PDF(LaTeX), EPUB  （WYSIWYGエディタがない）
• 35. Sphinxの処理、出力フォーマット
• 36. Sphinxのデータ変換イメージ
• 37. numfig: 図表番号(Sphinx-1.3b1) index.rst index.html conf.py
• 38. bizstyle: HTMLテーマ(Sphinx-1.3b1) Sphinx default Sphinx bizstyle
• 39. literalinclude:外部ソース埋め込み index.rst code/sample.rst
• 40. todo  文中に入れておきたい、「あとでやること」 preface.rst preface.html JenkinsのToDo検知 todolist.html
• 41. 執筆に使った/作ったSphinxの拡張 blockdiag  ダイアグラム図を書ける japanesesupport  reSTマークアップでどうしても入ってしまう空白を除去  時々除去しすぎて英単語同士がくっついてしまう column-directive  コラム用の体裁でレイアウトする自作ディレクティブ idx ロール  索引データを自動生成
• 42. 執筆用に作ったSphinxの拡張 Sphinx日本語バリデータ 各自がmake htmlするとNG項目を表示する  半角全角チェック: 英数カナ  ABCＡＢＣ123１２３アイウｱｲｳ-> ABC123アイウ  半角全角カッコチェック: 内容が全角ならカッコも全角  NG: （sphinx）(全角)  OK: (sphinx)（全角）  !? は全角直後では全角、半角直後では半角  NG: 日本語!!  OK: 日本語！！  全角直後のカンマ、ピリオドは禁止  用語辞書で指摘 用語辞書
• 43. 執筆用に作ったSphinxの拡張 rst2shuwa  秀和システム原稿 フォーマットでビ ルド  make shuwa -------> 3年前の資産！ （やっと元が取れそ う） （Pythonプロフェッショナルプログラミング2012年2月の最終稿よ
• 44. 校正戻し原稿の扱い  2012年は、秀和フォーマットで校正された データが戻ってきた  差分を手動でreSTに戻す作業が発生  今回はどうする？  最初から差分で受け取る・・これはこれ で大変そう
• 45. Sphinxのコミュニティー  Webサイト、資料:  http://sphinx-users.jp/  メーリングリスト:  http://sphinx-users.jp/mailinglist.html  イベント:  http://sphinx-users.jp/event/  Twitter:  #sphinxjp