Movatterモバイル変換

Sphinx-users.jp & Sphinxコミッター清水川貴之

自己紹介：清水川貴之 @shimizukawa  株式会社BeProud所属  Sphinxコミッター  Sphinx-users.jp お財布担当  一般社団法人PyConJP理事  Pepper レンタル中

Sphinxで執筆した書籍1 エキスパートPythonプログラミング 2010, アスキー・メディアワークス刊  翻訳者4名  Sphinxを使って書いた日本初の書籍（たぶん）  reSTで提出して、アスキーさんがEWBにがんばって変換  校正戻し以降は執筆側で両方メンテナンス地獄

エキPyシステム PDFからコピペ＆Sphinxに整形 SCM (Bazzar) reST 校正 reST -> -> make html 執筆確認レビュー Spreadsheetでレビュー指摘

エキPyシステム PDFからコピペ＆Sphinxに整形 SCM (Bazzar) 出版翻訳校正レビュー Spreadsheetでレビュー指摘

Sphinxで執筆した書籍2 Pythonプロフェッショナルプログラミング  執筆者14名  make shuwa で、Sphinxから直接提出用フォーマットで出力  人数多くてマークアップや文体を揃えるのが大変  校正戻し以降は執筆側で両方メンテナンス地獄 2012, 秀和システム刊

PyProシステム Sphinxの雛形作成 SCM (Mercurial) reST make html 執筆確認レビュー通知 Spreadsheetでレビュー指摘

PyProシステム Sphinxの雛形作成校正 make shuwa SCM (Mercurial) reST make html 執筆確認レビュー通知 Spreadsheetでレビュー指摘

PyProシステム校正 SCM (Mercurial) 執筆レビュー出版 Spreadsheetでレビュー指摘

Sphinxで執筆した書籍3 Sphinxをはじめよう（電子書籍） 2013, オライリー・ジャパン刊  執筆者4名  オライリーさんがmake xml からのRe:VIEW変換  リポジトリ直接校正のため、戻しがなくて平和

レビュー Sphinxをはじめようシステム Sphinxの雛形作成 SCM (Bitbucket) reST make html 執筆確認 Spreadsheetでレビュー指摘

レビュー Sphinxをはじめようシステム Sphinxの雛形作成 SCM (Bitbucket) reST make html 執筆確認出版 reST Re:VIEW 校正 make xml Spreadsheetでレビュー指摘

Sphinxで執筆中の書籍4 <- New!! Pythonプロフェッショナルプログラミング第2版  執筆者11名  make shuwa で、Sphinxから直接提出用フォーマットで出力 2015, 秀和システム刊（予定）  初版の原稿をreSTに戻してなかったのを反映  校正戻し以降は…どうなる？（そろそろ考える）

PyPro第2版システム前回のSphinx原稿 SCM (Mercurial) reST make html 執筆確認レビュー通知通知 Spreadsheetでレビュー指摘

PyPro第2版システム前回のSphinx原稿 SCM (Mercurial) reST make html 執筆確認レビュー通知 make shuwa Spreadsheetでレビュー指摘校正差分をもらう予定通知

PyPro第2版(2014/9 ~ 2015/02)

中央リポジトリ中央リポジトリ  Sphinx原稿管理  Push受付  Redmine の関連チケットにcommit表示  Jenkinsへ通知、ビルド  Slackへ通知SCM(Mercurial) チケット更新 reST 通知ビルド

執筆の工程 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原稿レビュー指摘 ① ② ③ ⑤ ④ ⑦ ⑥ ⑧ ⑨ ⑩

Redmine Redmine  進捗管理  チケット更新-> Slack通知, メール通知  リポジトリ更新検知-> チケット更新 SCM (Mercurial)

Jenkins  ビルド管理  リポジトリ更新検知  hg pull  pip install –r requirements.txt  make html pdf  ビルド成功  Slack通知  成果物を提供  ビルド失敗  Slack通知 SCM レビュー通知 PDF生成には、 TeXLive2014が必要。各執筆者は環境を持っていない。 TeXLive2014入り

Google Spreadsheet  レビュー指摘  Redmine等のチケットはあえて使わなかった  レビュアーにとって、チケットは重い（気がする）  Spreadsheetの長所、短所  他の人のレビュー状況がなんとなく分かる  さくさく書ける、緩い感じがして気軽  新しく指摘された部分が分からない通知はGASを書いて Slackに更新通知。差分は分からない。

出版社への提出工程(2012) 1. 私: hg pull 2. 私: make shuwa 3. 私: tar zcf bpbook20141205.tgz shuwa 4. 私: cp bpbook20141205.tgz ~/Dropbox 5. 私: メールで連絡 make shuwa 校正 ① ②③ ④ ⑤

執筆者執筆はreST、執筆者レビューはHTML レビュー指摘はRedmine、または直接編集

社内レビュー＆早期レビュー社内レビューはHTML or LaTeX PDF レビュー指摘はGoogle Spreadsheet

社外レビュー出版形式PDF（希望者にはHTML渡し）レビュー指摘はGoogle Spreadsheet

各フォーマットの比較 reStructuredText HTML LaTeX -> PDF 秀和システム原稿フォーマット

秀和システム原稿フォーマット&出力秀和システム原稿フォーマット出版用PDF出力

Sphinx誕生: 2007年作者: Georg Brandl 2007年にSphinxを開発  それまでLaTeXで作っていたPythonドキュメントが複雑すぎてメンテ不能に。簡単に扱えるツールが必要だった DocutilsのreStrucutredTextをベースに  reSTは、2002年にPythonのテキストマークアップとして採用されていた(PEP287) その他のコミッター Roland, @shimizukawa, @tk0miya

Docutils/reStructuredTextの特徴  ￥や｛｝で目がチカチカしない  レイアウト制御命令がない  レイアウトを意識せずに内容に集中できる  テキストのままでも読みやすい  一部のマークアップを拡張可能(role, directive) :idx: ロールを追加blockdiag directiveを追加→ 出力

Sphinxの特徴  Docutilsは単ページのみ。Sphinxは複数ページを扱う。  全てのページをツリー構造に繋ぐtoctree  複数のページを縦横に繋ぐ参照  各種フォーマットの出力  HTML, PDF(LaTeX), EPUB  （WYSIWYGエディタがない）

Sphinxの処理、出力フォーマット

Sphinxのデータ変換イメージ

numfig: 図表番号(Sphinx-1.3b1) index.rst index.html conf.py

bizstyle: HTMLテーマ(Sphinx-1.3b1) Sphinx default Sphinx bizstyle

literalinclude:外部ソース埋め込み index.rst code/sample.rst

todo  文中に入れておきたい、「あとでやること」 preface.rst preface.html JenkinsのToDo検知 todolist.html

執筆に使った/作ったSphinxの拡張 blockdiag  ダイアグラム図を書ける japanesesupport  reSTマークアップでどうしても入ってしまう空白を除去  時々除去しすぎて英単語同士がくっついてしまう column-directive  コラム用の体裁でレイアウトする自作ディレクティブ idx ロール  索引データを自動生成

執筆用に作ったSphinxの拡張 Sphinx日本語バリデータ各自がmake htmlするとNG項目を表示する  半角全角チェック: 英数カナ  ABCＡＢＣ123１２３アイウｱｲｳ-> ABC123アイウ  半角全角カッコチェック: 内容が全角ならカッコも全角  NG: （sphinx）(全角)  OK: (sphinx)（全角）  !? は全角直後では全角、半角直後では半角  NG: 日本語!!  OK: 日本語！！  全角直後のカンマ、ピリオドは禁止  用語辞書で指摘用語辞書

執筆用に作ったSphinxの拡張 rst2shuwa  秀和システム原稿フォーマットでビルド  make shuwa -------> 3年前の資産！（やっと元が取れそう）（Pythonプロフェッショナルプログラミング2012年2月の最終稿よ

校正戻し原稿の扱い  2012年は、秀和フォーマットで校正されたデータが戻ってきた  差分を手動でreSTに戻す作業が発生  今回はどうする？  最初から差分で受け取る・・これはこれで大変そう

Sphinxのコミュニティー  Webサイト、資料:  http://sphinx-users.jp/  メーリングリスト:  http://sphinx-users.jp/mailinglist.html  イベント:  http://sphinx-users.jp/event/  Twitter:  #sphinxjp

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

Movatterモバイル変換

Change Language

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

Embed presentation

Recommended

More Related Content

What's hot

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

More from Takayuki Shimizukawa

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