sphinxで日本語PDFを作成する方法

日本語PDFを作成する場合、いくつかの方法が公開されているが、
最も安定しているTEXLIVEを用いて作成する方法を取る。

まずは、texliveをインストールしておいてください。
また、pathを通す必要があります。

最新版のsphinxでは、make latexpdfja と打つと同等のコマンドが発行されるようです。

手順詳細

以下細かい手順を記載するが、理解したら最後に添付するスクリプトを自分用にうまく改造して利用してください。

TEXLIVEでは、以下の概要手順を踏む必要がある。
1. 画像ファイルを埋め込みの準備を行う。
2. sphinxで、LaTeXを作成する。
3. TEXLIVEでPDFを作成する。

1. 画像ファイルを埋め込みの準備を行う。

latexに画像を埋め込むには、\includegraphics を用いるが、(sphinxが、..figure:: 等を変換してくれている）
コレはデフォルトでは、画像のサイズをそのままpdfファイルに差し込もうとする。
pdfのサイズからはみ出すような画像を差し込むための縮小処理等は行われない。

したがって、以下2つのいずれか方法を取る。

1. 画像ファイルのサイズを目的のサイズに縮小する。
2. includegraphics をマクロで再変換する。

上記を組み合わせるのが良いが、まずは手っ取り早く2の方法を紹介する。
conf.py に以下の情報を編集、追加を行う。 LetLtxMacro
が、上記の説明の該当する行です。
# その他の行も関連するものもあるが、別途説明予定（準備中）

latex_elements = {
'pointsize': '10pt',
'papersize': 'a4paper',
'transition': '',
'extraclassoptions': ',openany,oneside',
'classoptions': ',dvipdfmx',
'babel': '\usepackage[japanese]{babel}',

}

latex_elements['preamble'] = r'''
\usepackage[export]{adjustbox}
\usepackage{letltxmacro}
\LetLtxMacro{origincludegraphics}{includegraphics}
\renewcommand*includegraphics[2][clip,scale=0.5,max width=textwidth,max height=textheight,keepaspectratio]{%
\begin{minipage}{columnwidth}
\begin{wrapfigure}{r}{columnwidth}
\origincludegraphics[#1]{#2}
\end{wrapfigure}
\end{minipage}
}
'''

イメージは以下のとおりである。

minipageとwrapfigureコマンドに置き換える事により、表示可能にする。
（但し、小さい画像に関しては、更に小さくなってしまう。）

2. sphinxで、LaTeXを作成する。

LaTeXを生成するためには、以下いずれかのコマンドを用いる。

1. make latex
2. sphinx-build -b latex [project_dir] [output_dir]

make latex でも内部的に、sphinx-buildが呼ばれるので、どちらでも良い。
.tex ファイルに1にて行った内容が反映されている事を確認する。
同様の文字列が含まれているはずである。

3. TEXLIVEでPDFを作成する。

_build/latex 配下に移動し、make all-pdf-ja コマンドを発行する。
上記のコマンドの中で行われている手順は以下の通りである。

3.1. 画像ファイルを埋め込み用の変換を施す

latex用に画像の埋め込み情報を生成する。

以下のコマンドを用いて、画像ファイルにbouncy box情報を付与する。

note

for f in .pdf.png .gif.jpg *.jpeg; do extractbb \$\$f; done

3.2. tex から、dvi ファイルを生成する。

以下のコマンドを発行する。
何度も実行するのは、目次ファイルを生成して、再度付与するためである。
（お作法なので、キにしないように

note

for f in .tex; do platex -kanji=utf8 \$(LATEXOPTS) \$\$f; done
for f in *.tex; do platex -kanji=utf8 \$(LATEXOPTS) \$\$f; done
for f in *.tex; do platex -kanji=utf8 \$(LATEXOPTS) \$\$f; done
for f in *.idx; do mendex -U -f -d "basename \$\$f .idx.dic" -s python.ist \$\$f; done
for f in *.tex; do platex -kanji=utf8 \$(LATEXOPTS) \$\$f; done
for f in .tex; do platex -kanji=utf8 \$(LATEXOPTS) \$\$f; done

3.3. dviから、PDFを生成する。

dvi ファイルから、pdfを生成する。

note

for f in *.dvi; do dvipdfmx \$\$f; done

なぜか、最初は以下のコマンドが失敗するので、別途自分で実行する必要があるかも知れない。

pdf生成スクリプト

以下は、Mac OS XとLinux(Ubuntu)にて、日本語PDFを生成するサンプルです。
筆者は、Linux上のJenkinsで以下のスクリプトを実行しています。

#!/bin/bash

SPHINX_PJDIR=/path/to/sphinx_pj/

cd \$(SPHINX_PJDIR) make latex

cd _build/latex

# Loading texlive environment.
if [ \$dist = 'Darwin' ]; then
export PATH=\$PATH:/usr/local/texlive/2013/bin/x86_64-darwin/
fi

if [ \$dist = 'Linux' ]; then
export PATH=\$PATH:/usr/local/texlive/2013/bin/x86_64-linux
fi

make all-pdf-ja
dvipdfmx Android.dvi