Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

執筆中のPythonプロフェッショナルプログラミング第2版でsphinxを使っている話

6,715 views

Published on

Sphinxを出版に使っている事例。
以下の書籍の執筆にSphinxを使った際のシステム構成などを紹介。
・エキスパートPythonプログラミング
・Pythonプロフェッショナルプログラミング
・Sphinxをはじめよう
・Pythonプロフェッショナルプログラミング第2版

Published in: Technology
  • Be the first to comment

執筆中のPythonプロフェッショナルプログラミング第2版でsphinxを使っている話

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

×