ドキュメント生成ツールの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ゴシックフォント
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が生成される！
参考
下記の先人達を参考にしました。感謝。
- Sphinxを使ってPDFドキュメントを生成する - azlab 開発Memo
- rst2pdfをWindowsで使ってみた - 偏った言語信者の垂れ流し
- Sphinxで日本語PDFを生成する - 湘南ぱいそん
- rst2pdfを使うには - Fly me to the Helios
