Sphinx-users.jp & Sphinxコミッター

清水川貴之

自己紹介：清水川貴之

@shimizukawa

株式会社BeProud所属

Sphinxコミッター

Sphinx-users.jp お財布担当

一般社団法人PyConJP理事

Pepper レンタル中

Sphinxで執筆した書籍1

翻訳者4名

Sphinxを使って書いた日本初の書籍（たぶん）

reSTで提出して、アスキーさんがEWBにがんばって変換

校正戻し以降は執筆側で両方メンテナンス地獄

エキスパートPythonプログラミング2010, アスキー・メディアワークス刊

エキPyシステム

PDFからコピペ＆Sphinxに整形

SCM(Bazzar)

reSTreST->->

make html

執筆

確認

レビュー

校正

Spreadsheetでレビュー指摘

エキPyシステム

PDFからコピペ＆Sphinxに整形

SCM(Bazzar)

出版

翻訳

校正

レビュー

Spreadsheetでレビュー指摘

Sphinxで執筆した書籍2

執筆者14名

make shuwaで、Sphinxから

直接提出用フォーマットで出力

人数多くてマークアップや文体を揃えるのが大変

校正戻し以降は執筆側で両方メンテナンス地獄

Pythonプロフェッショナルプログラミング2012, 秀和システム刊

PyProシステム

Sphinxの雛形作成

SCM(Mercurial)

reST

make html

執筆

確認

レビュー

通知

Spreadsheetでレビュー指摘

PyProシステム

make shuwa 校正Sphinxの雛形作成

SCM(Mercurial)

reST

make html

執筆

確認

レビュー

通知

Spreadsheetでレビュー指摘

PyProシステム

校正

SCM(Mercurial)

執筆

レビュー

出版

Spreadsheetでレビュー指摘

Sphinxで執筆した書籍3

執筆者4名

オライリーさんがmake xmlからのRe:VIEW変換

リポジトリ直接校正のため、戻しがなくて平和

Sphinxをはじめよう（電子書籍）2013, オライリー・ジャパン刊

レビュー

Sphinxをはじめようシステム

Sphinxの雛形作成

SCM(Bitbucket)

reST

make html

執筆

確認

Spreadsheetでレビュー指摘

レビュー

Sphinxをはじめようシステム

Sphinxの雛形作成

SCM(Bitbucket)

reST

make html

執筆

確認

出版

reSTRe:VIEW

校正

make xml

Spreadsheetでレビュー指摘

Sphinxで執筆中の書籍4 <- New!!

執筆者11名

make shuwaで、Sphinxから

直接提出用フォーマットで出力

初版の原稿をreSTに戻してなかったのを反映

校正戻し以降は…どうなる？（そろそろ考える）

Pythonプロフェッショナルプログラミング第2版

2015, 秀和システム刊（予定）

PyPro第2版システム

前回のSphinx原稿

SCM(Mercurial)

reST

make html

執筆

確認

レビュー

通知

Spreadsheetでレビュー指摘

通知

PyPro第2版システム

前回のSphinx原稿

SCM(Mercurial)

reST

make html

執筆

確認

レビューSpreadsheetでレビュー指摘

通知

make shuwa 校正

差分をもらう予定

通知

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

PyPro第2版システム

前回のSphinx原稿

SCM(Mercurial)

reST

make html

執筆

確認

レビューSpreadsheetでレビュー指摘

通知

make shuwa 校正

差分をもらう予定

通知

中央リポジトリ

中央リポジトリ

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

秀和システム原稿フォーマット

SphinxのＨＴＭＬ出力

Sphinxの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)

conf.py

index.rst index.html

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

Sphinx bizstyleSphinx default

literalinclude:外部ソース埋め込み

index.rst code/sample.rst

todo

文中に入れておきたい、「あとでやること」

JenkinsのToDo検知

preface.rst preface.html

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