Sphinxを使ってPDFドキュメントを生成する(続き)

SphinxはreStructuredTextという言語で記述されたファイルを元にHTMLやPDFなどのドキュメントを出力するPythonのツールです。

前回はSphinxからPDF出力を行うと日本語フォントの埋め込みに失敗するというところまででした。その後、rst2pdf単体で使用した場合には問題なかったので、rst2pdfのSphinxエクステンションに原因があるだろうと思い調査したところ、それらしいポイントは見つかったのですが、私のPythonスキルの問題もあり修正できないうちに放置してしまいました。。

今回、作業用のPCのOSをクリーンインストールしたので、環境構築から試してみたところrst2pdfのtrunkではこの問題は修正されていることがわかりました。

以下に追加・整理したWindows環境でのセットアップの手順です。

インストール

Python

Windows installer形式をダウンロードしてインストールします。
http://www.python.org/

環境変数PATHに以下を追加します（Python26はPythonのインストール先フォルダ）。

C:\Python26
C:\Python26\Scripts

setuptools

easy_installを使うために、setuptoolsをインストールします。
Pythonのバージョンにあわせたexe形式のファイルをダウンロードしてインストールします。
http://pypi.python.org/pypi/setuptools

Sphinx

Sphinxをインストールします。

easy_install sphinx

rst2pdf

SphinxからrstファイルをPDFに変換するためのrst2pdfをインストールします。
rst2pdfのtrunkをチェックアウトします。
http://rst2pdf.googlecode.com/svn/trunk/

チェックアウトしたフォルダに移動して、rst2pdfをインストールします。

python setup.py install

ReportLab Toolkit

Python用PDF作成ライブラリのReportLab Toolkitをインストールします。
http://www.reportlab.com/software/opensource/rl-toolkit/

Python Imaging Library(PIL)

画像処理ライブラリをインストールします。
http://www.pythonware.com/products/pil/

PDF埋め込み用フォント

以下のフォントをダウンロードしzipファイルに含まれるttfおよびotfファイルをC:\WINDOWS\Fontsにコピーします。

IPAフォント(http://ossipedia.ipa.go.jp/ipafont/)
VLゴシックフォント(http://dicey.org/vlgothic/)

スタイルシートの作成

スタイルシートを作成します。ファイル名はja.jsonとしました。

{
  "embeddedFonts" :
[["VL-Gothic-Regular.ttf","VL-PGothic-Regular.ttf","ipam.otf","verdanaz.ttf"]],
  "fontsAlias" : {
    "stdFont": "VL-PGothic-Regular",
    "stdBold": "VL-PGothic-Regular",
    "stdItalic": "VL-PGothic-Regular",
    "stdBoldItalic": "VL-PGothic-Regular",
    "stdMono": "VL-PGothic-Regular",
    "stdMonoBold": "VL-PGothic-Regular",
    "stdSanBold": "VL-PGothic-Regular",
    "stdSansBold": "VL-PGothic-Regular"
  },
  "styles" : [
    ["base" , {
      "wordWrap": "CJK",
      "kerning" : true
    }],
    ["literal" , {
      "wordWrap": "None"
    }]
  ]
}

ここでは、フォントはすべてVLゴシックの可変幅フォントを指定しています。
イタリックとボールドについては対応方法がわかりません。

rst2pdfからのPDF作成

まずrst2pdfからPDFファイルを作成してみます。

rst2pdf -s ja --font-path=C:\WINDOWS\Fonts -o index.pdf index.rst

これで日本語を含むPDFが正常に作成できました。

Sphinxからrst2pdfを実行する設定

config.pyに設定を追加します。これはrst2pdfのマニュアルに書かれているとおりです。

まず、extensionsの部分に以下を追加します。

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

次にPDF用の設定を追加し、pdf_documents、pdf_font_path、pdf_stylesheetsあたりを編集します。

# -- 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','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 = ['c:\windows\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

make.batに以下の記述を追加します。

if "%1" == "pdf" (
	%SPHINXBUILD% -b pdf %ALLSPHINXOPTS% %BUILDDIR%/pdf
	echo.
	echo.Build finished. The PDF file is in %BUILDDIR%/pdf.
	goto end
)

SphinxからのPDFの作成

make.bat pdf

トラブルシューティング

AttributeError: 'module' object has no attribute 'graphviz'が発生する

conf.pyのextensionsに'sphinx.ext.graphviz'が抜けていると発生します。

AttributeError: _Container instance has no attribute '_hAlignAdjust'が発生する

これはtrunkでは直っています。easy_installなどでリリースバージョンのファイルをインストールしていると発生します。以下の対応方法があります。
http://code.google.com/p/rst2pdf/issues/detail?id=262

UnicodeDecodeErrorが発生する

これはSphinxは関係ないですが、パスに日本語のフォルダ名が含まれていると発生します。