Sphinxを使って日本語PDFを出力する

追記

Sphinx-Users-JPの下記記事をがより詳細に。

SphinxでPDFファイル作成

ドキュメント生成ツールのSphinxがよさげ。なのだけど日本語PDFに苦戦したので投稿しとく。

環境

Fedora12
Python2.6.2（Fedora12に初期状態で入っている）

Sphinx

ドキュメント

Sphinxについては渋川さんが翻訳されたドキュメントがある。

http://pypi.python.org/pypi/Sphinx

wget http://pypi.python.org/packages/source/S/Sphinx/Sphinx-0.6.3.tar.gz
tar zxf Sphinx-0.6.3.tar.gz
cd Sphinx-0.6.3
python setup.py install

Sphinxのインストール完了。

Sphinxプロジェクトの作成

Sphinxプロジェクトを作成したいディレクトリで下記コマンドを実行。

sphinx-quickstart

たくさん質問されるから答える。
日本語PDFを生成するためなら聞かれたオプションはデフォルト値のままでOK。

プロジェクトが生成されたら（オプションにもよるけど）こんな感じのディレクトリになっているはず。

.
|-- Makefile
|-- build
|-- make.bat
`-- source
    |-- _static
    |-- _templates
    |-- conf.py
    `-- index.rst

試しにHTMLを生成してみる。

make html

すると、build/htmlの配下に生成される。（あ、jQuery使ってるんだー）

.
|-- Makefile
|-- build
|   |-- doctrees
|   |   |-- environment.pickle
|   |   `-- index.doctree
|   `-- html
|       |-- _sources
|       |   `-- index.txt
|       |-- _static
|       |   |-- basic.css
|       |   |-- default.css
|       |   |-- doctools.js
|       |   |-- file.png
|       |   |-- jquery.js
|       |   |-- minus.png
|       |   |-- plus.png
|       |   |-- pygments.css
|       |   `-- searchtools.js
|       |-- genindex.html
|       |-- index.html
|       |-- objects.inv
|       |-- search.html
|       `-- searchindex.js
|-- make.bat
`-- source
    |-- _static
    |-- _templates
    |-- conf.py
    `-- index.rst

rst2pdf

次にreStructuredTextをPDF化してくれるrst2pdfを入れる。
http://code.google.com/p/rst2pdf/

wget http://rst2pdf.googlecode.com/files/rst2pdf-0.12.3.tar.gz
tar zxf rst2pdf-0.12.3.tar.gz
cd rst2pdf-0.12.3
python setup.py install

rst2pdfのSphinxとの連携は下記に記載がある。
http://rst2pdf.googlecode.com/svn/trunk/doc/manual.txt
埋込み用フォントをインストール後設定する。

埋込み用フォントのインストール

今回の日本語PDFの出力で、一番苦戦したのがここ。

IPAフォントとVLゴシックフォントをインストール。

IPAフォント

http://ossipedia.ipa.go.jp/ipafont/

wget http://info.openlab.ipa.go.jp/ipafont/fontdata/IPAfont00301.zip
unzip IPAfont00301.zip
cd IPAfont00301

フォントファイル.otfをFedoraのフォントディレクトリにコピー

cp *.otf /usr/share/fonts/

VLゴシックフォント

http://dicey.org/vlgothic/

wget http://jaist.dl.sourceforge.jp/vlgothic/44715/VLGothic-20091202.zip
unzip VLGothic-20091202.zip 
cd VLGothic

IPAフォントと同様に.ttfファイルをフォントディレクトリにコピー

cp *.ttf /usr/share/fonts/

Sphinxとrst2pdfの連携

http://rst2pdf.googlecode.com/svn/trunk/doc/manual.txt
に記載されてる。

extensionsの書き換え

source/conf.pyのextensionsを書き換える。

extensions = ['sphinx.ext.autodoc','rst2pdf.pdfbuilder']

PDFのオプションを設定

source/conf.pyに下記を追加する。

# -- Options for PDF output --------------------------------------------------

# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
# If there is more than one author, separate them with \\.
# For example: r'Guido van Rossum\\Fred L. Drake, Jr., editor'
#
# The options element is a dictionary that lets you override 
# this config per-document.
# For example, 
# ('index', u'MyProject', u'My Project', u'Author Name', 
#  dict(pdf_compressed = True))
# would mean that specific document would be compressed
# regardless of the global pdf_compressed setting.
    
pdf_documents = [ 
    ('index', u'MyProject', u'My Project', u'Author Name'),
]

# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ['sphinx','kerning','a4','ja']

# Create a compressed PDF
# Use True/False or 1/0
# Example: compressed=True
#pdf_compressed = False

# A colon-separated list of folders to search for fonts. Example:
pdf_font_path = ['/usr/share/fonts']

# Language to be used for hyphenation support
pdf_language = "ja"
    
# Mode for literal blocks wider than the frame. Can be
# overflow, shrink or truncate
#pdf_fit_mode = "shrink"

# Section level that forces a break page.
# For example: 1 means top-level sections start in a new page
# 0 means disabled
#pdf_break_level = 0

# When a section starts in a new page, force it to be 'even', 'odd',
# or just use 'any'
#pdf_breakside = 'any'

# Insert footnotes where they are defined instead of 
# at the end.
#pdf_inline_footnotes = True

# verbosity level. 0 1 or 2
#pdf_verbosity = 0

# If false, no index is generated.
#pdf_use_index = True

# If false, no modindex is generated.
#pdf_use_modindex = True

# If false, no coverpage is generated.
#pdf_use_coverpage = True

# Documents to append as an appendix to all manuals.    
#pdf_appendices = []

# Enable experimental feature to split table cells. Use it
# if you get "DelayedTable too big" errors
#pdf_splittables = False

# Set the default DPI for images
#pdf_default_dpi = 72

Makefileにpdfを追加

Makefileにpdfを追加する。

pdf:
    $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) build/pdf
    @echo
    @echo "Build finished. The PDF files are in build/pdf."

スタイルシートの設定

Sphinxプロジェクト直下にja.jsonファイルを作成する。

{
  "embeddedFonts" :
[["VL-Gothic-Regular.ttf","VL-PGothic-Regular.ttf","ipam.otf","ipag.otf","ipagp.otf","ipamp.otf"]],
  "fontsAlias" : {
    "stdFont": "VL-PGothic-Regular",
    "stdBold": "VL-PGothic-Regular",
    "stdItalic": "VL-PGothic-Regular",
    "stdMono": "VL-Gothic-Regular"
  },
  "styles" : [
    ["base" , {
      "wordWrap": "CJK"
    }],
    ["literal" , {
      "wordWrap": "None"
    }]
  ]
}

2行目あたりで今回追加したIPAフォントとVLゴシックフォントを設定してる。（このコードだとVL-PGothic-Regularしか設定してないけど...）

試す

日本語の.rstファイルを作り下記コマンドを実行。

make pdf

すると、
build/pdf/にpdfが日本語PDFが生成される！

参考

下記の先人達を参考にしました。感謝。