SphinxでPDFファイル作成

ドキュメントの成果物として、保存したり印刷したりする用途で好まれるのがPDFです。 SphinxではLaTeXを利用したPDF出力が可能です。

本ドキュメントは日本語で出力する場合についての手順を紹介します。

Sphinx で利用する TeXディストリビューション

Sphinx で日本語文章を書く場合は文字コードに UTF-8が利用されるため、PDF を作成する際には UTF-8 対応版の pLaTeX である必要があります。内部では ebb, mendex, platex, dvipdfmx の各コマンドを利用していますので、これらが利用できる環境を用意します。

../../_images/texlive_web.png

ここでは、Windows、macOS、Linux、FreeBSDなどに対応しており、環境の作りやすさを考慮して、 TeX Live というディストリビューションを使って説明をしていきます。

注釈

TeXの処理系の中には、アスキー・メディアワークスが開発を行っていて、日本語の扱いに長けたpTeX/pLaTeXがあります。 TeX Live 2010からは、このpLaTeXも内蔵されたため、簡単に品質の高い日本語のドキュメントが作れるようになりました。

TeX Liveのインストール

Sphinxプロジェクトの作成/再作成

sphinx-quickstart コマンドでSphinxプロジェクトを作成します。

もし既存のプロジェクトがある場合でも、新規にプロジェクトを作成して rst ファイルやテンプレート、静的ファイルなどを上書きコピーしてください。これは、古いバージョンのSphinxで生成された conf.pyMakefile が日本語出力に対応していないために上書き更新をするために行ないます。

注釈

既にindex.rstのコンテンツがある場合は、一旦退避して、sphinx-quickstart後に書き戻します。

Sphinxプロジェクトの設定変更

sphinx-quickstart コマンドで生成した conf.py に日本語用の設定を書き加えます。

# 言語の設定
language = 'ja'

# LaTeX の docclass 設定
latex_docclass = {'manual': 'jsbook'}

注釈

この設定をしない場合、「しおり」が作成されなかったり、文字化けすることがあります。

ビルドの実行

make latexpdf と実行すれば、ファイルが生成されます。

注釈

1.5より前のバージョンでは、latexpdfjaとタイプしていください。1.5以降は他の言語と仕組みが統合されたので末尾のjaは省略できるようになりました。互換性のためにjaを付けてもビルドはできます。

$ make latexpdf
sphinx-build -b latex -d build/doctrees   source build/latex
Making output directory...
Running Sphinx v1.1.2
loading translations [ja]... done
loading pickled environment... not yet created
building [latex]: all documents
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
processing test.tex... index
resolving references...
writing... WARNING: no Babel option known for language 'ja'
done
copying TeX support files... done
build succeeded, 1 warning.
Running LaTeX files through platex and dvipdfmx...
make -C build/latex all-pdf-ja
()
pdflatex finished; the PDF files are in build/latex.

お疲れ様でした!これでPDFファイルができました。

PDFの完成

ビルドディレクトリ配下のlatexディレクトリ(デフォルト設定の場合は _build/latex)にPDFファイルが生成されているはずです。

注釈

フォントの埋め込み

Kindle などの一部のPDFリーダーで文字を正しく表示するには、PDFファイルにフォントを埋め込むとよいでしょう。フォント埋め込みにはいくつかの方法があります。以下のコマンドで、TeX Liveの環境をフォント埋め込みに変更できます。

sudo kanji-config-updmap-sys auto

埋め込みしない設定に戻すには以下を実行します。

sudo kanji-config-updmap-sys nofont

変更履歴

2010/10/10:

初版(渋川)

2012/03/25:

打田さんの Sphinx パッチおよび TeX Live 2011 をベースに記事を更新

2014/01/26:

MacPortsによるOSXへのインストール、FreeBSDへのインストールを追加し、記事を再構成&更新 (波田野)

2017/02/23:

make latexpdfja -> make latexpdf (渋川)

2018/08/19:

古い情報を削除 (うさ)

2019/11/29:

LaTeXのインストールについてWindows、macOS、Linuxの情報を更新(hidaruma)

2019/12/16:

フォント埋め込み方法について記述を追加 (shimizukawa)