SphinxでかんたんePubファイル作成

日時:2010/05/21
作者:渋川よしき
最終更新:2010/09/13

Sphinxの1.0からは、ePubファイルのビルドができるようになります。ePubファイルというのは、iPadやソニーの電子ブックリーダーなどで利用できる、電子ブックのフォーマットです。原理的にはHTMLに、決まった形式のメタデータを含むファイルを追加して、zipで固めて拡張しをepubにしたものですが、Sphinxを使えば簡単に出力することができます。

注釈

iPadでの表示、インストールの仕方は @takabow に協力いただきました。ありがとうございます。

Sphinx 1.0のインストール

まずはSphinx 1.0以降をインストールします。通常のeasy_install(もしくはdistribute, pip)を利用したインストール方法でインストールできます。

$ sudo python setup.py -U install

必要なファイルも取得してインストールしてくれます。これで準備完了です。

プロジェクトの作成

通常通り、sphinx-quickstartコマンドを使ってドキュメントのプロジェクトフォルダの環境を設定します。ただし、1.0になると、いくつかビルダーの選択肢が増えるとともに、いくつかオプションが変わっていますので、既存のドキュメントをePub化したい場合にも、sphinx-quickstartを実行してMakefileなどを作り直すことをおすすめします。なお、現在のバージョンでは生成されるconf.pyはほぼ変わっていませんが、これから手が加わる可能性もあります(後からマニュアルを見ながら追加すればいいので問題はありません)。

後はチュートリアルなどを見ながら、通常通りにSphinxを使ってドキュメントを書き上げていきます。make htmlを使ってプレビューをしながら書いていくのが良いでしょう。

ePubの設定を追加

次に、ePubのオプションを見ながら、conf.pyにePub用の設定を追加していきます。以前のバージョンのsphinx-quickstartでプロジェクトを作った場合には、conf.pyにこれらのオプションの追加をしてくれないため、自分で書き加える必要があります。

現在のバージョンでは、途中で「ePub用の設定を加えるか?」ということを聞いてきます。忘れずに「Y」を選択しましょう。

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]:

次のリストは、ePub関連の、生成されるファイルに直に効いてくるオプションの一覧です。

epub_basefile:ePubファイルの名前になります。省略すると生成されなくなりますので注意。
epub_theme:テーマファイルです。デフォルトはepubです。
epub_tocdepth:索引の深さを指定します。文書量にもよりますが、2〜3が適当でしょう。

次のリストは、ePubのページ構成に変更を与えるオプションです。

epub_pre_files:文章のページの前に埋め込むファイル群
epub_post_files:
 文章のページの後ろに埋め込むファイル群
epub_exclude_files:
 ePub化するときには除外するファイル群

次のリストは、メタデータとして書き込まれるオプションです。

epub_title:ドキュメントのタイトルです。iPadの先頭ページに埋め込まれます。
epub_author:ドキュメントの著者名です。iPadの先頭ページに埋め込まれます。
epub_language:言語
epub_publisher:出版社
epub_copyright:著作権
epub_identifier:
 識別子。ISBN, URLなど。
epub_scheme:識別子の種類。ISBNURL
epub_uid:ユニークな識別子。

Expert PythonのサンプルePubを生成するconf.pyでは次のように設定しています。

project = u'エキスパートPythonプログラミング 10章サンプル'
epub_title = project

copyright = u'Packt Publishing 2008, ASCII MEDIA WORKS Inc., Copyright 2010'
epub_author = u'2010, Tarek Ziade著、稲田直哉、渋川よしき、清水川貴之、森本哲也訳'

epub_basename = 'expert_python_programming_sample'
epub_language = u'ja'
epub_publisher = u'Packt Publishing / アスキー・メディアワークス'
epub_identifier = u'http://ascii.asciimw.jp/books/books/detail/978-4-04-868629-7.shtml'
epub_scheme = 'URL'
epub_tocdepth = 3

刊行物であればepub_identifierはISBNになりますが、あくまで10章サンプルと、本そのものは違うということで、ここでは書籍情報のURLを設定しています。

警告

現時点のバージョンでは、languageオプションを'ja'に設定するとエラーになります。

ビルドと確認

いつものようにmakeします。ビルダー名はepubになります。

(sphinx10)MacBook:chapter10 shibu$ make epub
sphinx-build -b epub -d _build/doctrees   . _build/epub
Making output directory...
Running Sphinx v1.0pre
(中略)
writing expert_python_programming_sample.epub file...

Build finished. The epub file is in _build/epub.

_build/epub/フォルダの下にexpert_python_programming_sample.epubファイルが作成されます。

PC上で確認するには、PC用のePubビューアを利用します。ここでは、Python製のオープンソース版電子ブック用iTunesとも言うべき、Calibreを利用しました。

注釈

なぜかAdobe Digital Editionでは文字化けしてしまい、読むことができませんでした。

警告

電子ブックなのでKindleビューアを利用したくなるかもしれませんが、KindleはePubではなく、別形式(azw/mobi)を利用しているため利用できません。

../../_images/calibre_library.png

ライブラリのページにドラッグ&ドロップすると追加されます。追加されたドキュメントを右クリックして、View -> Viewを選ぶか、選択状態でキーボードのVを叩くと、表示されるようになります。

../../_images/calibre_viewer.png

iPadへのインストールと表示

iPadに入れるには、iPadをコンピュータに接続します。次にiTunesを開き、接続したiPadのブックというフォルダにePubファイルをドラッグ&ドロップします。

../../_images/itunes.png

iPadのiBooksを起動すると、ライブラリに追加されています。これで後から読むことができます。

../../_images/ibooks.jpg ../../_images/ipad.jpg

1.0のsphinx-quickstartで追加される内容

Sphinx 1.0のsphinx-quickstartでは、途中でEPubビルダーを使用するか質問があります。もし、間違ってNにしてしまった、過去のバージョンから乗り換えたが、既に色々書き換えてしまったのでconf.pyの再作成は手間がかかるのでやりたくない、という方はこれをコピペして修正してください。

# -- Options for Epub output ---------------------------------------------------

# Bibliographic Dublin Core info.
epub_title = 'プロジェクト名'
epub_author = '著者名'
epub_publisher = '著者名'
epub_copyright = '年+著者名'

# The language of the text. It defaults to the language option
# or en if the language is not set.
#epub_language = ''

# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''

# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''

# A unique identification for the text.
#epub_uid = ''

# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []

# HTML files shat should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []

# A list of files that should not be packed into the epub file.
#epub_exclude_files = []

# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3

# Allow duplicate toc entries.
#epub_tocdup = True

変更履歴

2010/09/13:Sphinx 1.0正式リリースの変更点に合わせて修正