Sphinxの最近のブログ記事

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

環境

Fedora12

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

Sphinx

ドキュメント

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

• Sphinx - 渋川さん翻訳


• Sphinx - Original

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が生成される！

参考

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

• Sphinxを使ってPDFドキュメントを生成する - azlab 開発Memo


• rst2pdfをWindowsで使ってみた - 偏った言語信者の垂れ流し


• Sphinxで日本語PDFを生成する - 湘南ぱいそん


• rst2pdfを使うには - Fly me to the Helios