sphinx, rst2pdf, plantumlでUMLのクラス図入り本文日本語テキストをpdfに変換してみた

# はじめに

sphinx, rst2pdf, plantumlでUMLのクラス図入り本文日本語テキストをpdfに変換してみて、とりあえずうまく行ったのでメモしておきます。

サンプルプロジェクトのソースは
[hnakamur/sphinx-rst2pdf-plantuml-japanese-example](https://github.com/hnakamur/sphinx-rst2pdf-plantuml-japanese-example)
に置きました。

出力されたサンプルPDFは
https://hnakamur.github.io/sphinx-rst2pdf-plantuml-japanese-example/MyProject.pdf
です。

動作環境はOSX 10.8.5です。

# セットアップ

## VLゴシックフォントをインストール
[ダウンロードページ](http://vlgothic.dicey.org/download.html)から[VLGothic-20130607.tar.bz2](https://sourceforge.jp/projects/vlgothic/downloads/58961/VLGothic-20130607.tar.bz2)をダウンロードして展開し、
Finderで*.ttlファイルをOSXのFont Bookアプリにドラッグ＆ドロップします。
ファイルは~/Library/Fonts/にコピーされます。

## Pythonをインストール

私はanyenvでインストールしました。zshをお使いの場合は下記の手順で~/.bash_profileを~/.zprofileに変更してください。

```shell-session
git clone https://github.com/riywo/anyenv ~/.anyenv
cat <<'EOF' >> ~/.bash_profile

# anyenv
export PATH="$HOME/.anyenv/bin:$PATH"
eval "$(anyenv init -)"
EOF
exec $SHELL -l
```

## plantumlのインストール

Homebrewでインストールしました。

```shell-session
brew install plantuml
```

## fontconfigのインストール

これもHomebrewでインストールしました。

```shell-session
brew install fontconfig
```

### サンプルのセットアップ

```shell-session
git clone https://github.com/hnakamur/sphinx-rst2pdf-plantuml-japanese-example
cd sphinx-rst2pdf-plantuml-japanese-example
virtualenv env
source env/bin/activate
pip install -r pip_requirements.txt
```

#### 一から行う場合

```shell-session
mkdir work
cd work
virtualenv env
source env/bin/activate
pip install Sphinx
pip install rst2pdf
pip install sphinxcontrib-plantuml
```

```shell-session
sphinx-quickstart
```

を実行し、質問に適宜回答して、ひな形のファイルとディレクトリを作成。

conf.pyとMakefileを適宜編集。
ja.jsonを追加。

詳しくは
https://github.com/hnakamur/sphinx-rst2pdf-plantuml-japanese-example/commit/cac84fd210b0d891f0555dfbd8061d17a6082200
https://github.com/hnakamur/sphinx-rst2pdf-plantuml-japanese-example/commit/cac84fd210b0d891f0555dfbd8061d17a6082200
を参照してください。

### conf.pyを適宜調整

```
project = u'sphinx rst2pdf example'
copyright = u'2014, Hiroaki Nakamura'
```

```
plantuml = ['java', '-jar', '/usr/local/Cellar/plantuml/7994/plantuml.7994.jar']
```

あたりの行を適宜変更します。

## PDFファイルの生成

```shell-session
make pdf
```

## 生成されたPDFファイルをプレビュー.appで開く

```shell-session
open _build/pdf/MyProject.pdf
```

# 参考にしたページ

* [rst2pdf拡張を使ったPDFファイル作成 — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会](http://sphinx-users.jp/cookbook/pdf/rst2pdf.html)
* [(6日目) Sphinx 拡張の紹介 - Hack like a rolling stone](http://tk0miya.hatenablog.com/entry/20111206/p1)
* [p.26](http://www.slideshare.net/TakeshiKomiya/sphinx-2013/26) in [Sphinx ではじめるドキュメント生活 2013 #sphinxconjp](http://www.slideshare.net/TakeshiKomiya/sphinx-2013)

ありがとうございます！

# 試行錯誤メモ

## フォントの指定
ja.jsonのフォント指定がうまく行っているかはよくわかっていません。
というのも当初make pdfを実行すると以下のようにVL-Gothic-Regular.ttfがUnkown fontと言われていました。

```
(env)% make pdf
sphinx-build -b pdf -d _build/doctrees   . _build/pdf
Running Sphinx v1.2.2
loading pickled environment... done
building [pdf]: targets for 7 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
processing MyProject... index
resolving references...
done
writing MyProject... sh: fc-match: command not found
[ERROR] findfonts.py:208 Unknown font: VL-Gothic-Regular.ttf
sh: fc-match: command not found
[ERROR] findfonts.py:208 Unknown font: VL-Gothic-Regular.ttf
[ERROR] styles.py:308 Error processing font VL-Gothic-Regular: list index out of range
[ERROR] styles.py:309 Registering VL-Gothic-Regular.ttf as Helvetica alias
sh: fc-match: command not found
[ERROR] findfonts.py:208 Unknown font: VL-PGothic-Regular.ttf
sh: fc-match: command not found
[ERROR] findfonts.py:208 Unknown font: VL-PGothic-Regular.ttf
[ERROR] styles.py:308 Error processing font VL-PGothic-Regular: list index out of range
[ERROR] styles.py:309 Registering VL-PGothic-Regular.ttf as Helvetica alias
done
build succeeded.

Build finished. The PDF files are in _build/pdf.
```

ググってみるとfc-matchはfontconfigに入っているとのことなのでHomebrewでインストールしました。

```shell-session
brew install fontconfig
```

するとエラーは出なくなりました。

```shell-session
(env)% make pdf
sphinx-build -b pdf -d _build/doctrees   . _build/pdf
Running Sphinx v1.2.2
loading pickled environment... done
building [pdf]: targets for 7 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
processing MyProject... index
resolving references...
done
writing MyProject... done
build succeeded.

Build finished. The PDF files are in _build/pdf.
(env)% open _build/pdf/MyProject.pdf
```

ただ、フォントの違いに鈍い私が見る分には、fontconfigの有る無しでPDFの見た目に違いは無さそう気がしました。

<blockquote class="twitter-tweet" lang="ja"><p><a href="https://twitter.com/hnakamur2">@hnakamur2</a> フォントは何が使われているかとか埋め込まれているかとかは、ちょっと試した感じだと poppler の pdffonts コマンドで調べられそうでした。</p>&mdash; Kazuhiro NISHIYAMA (@znz) <a href="https://twitter.com/znz/statuses/470101752650280960">2014, 5月 24</a></blockquote>
と教えてもらいました。ありがとうございます。

```shell-session
brew install poppler
```

でインストールして試してみると以下の様な結果になりました。

```
(env)% pdffonts _build/pdf/MyProject.pdf
name                                 type              encoding         emb sub uni object ID
------------------------------------ ----------------- ---------------- --- --- --- ---------
AAAAAA+VL-PGothic-Regular            TrueType          WinAnsi          yes yes yes     20  0
AAAAAA+VL-Gothic-Regular             TrueType          WinAnsi          yes yes yes     24  0
```

```man pdffonts```によると```emb```列は```"yes" if the font is embedded in the PDF file```とのことなので、
VLゴシックフォントが埋め込まれていることが確認できました。

# LaTeXでの変換も試してみました
[sphinxでplantumlの図入り日本語テキストをlatexpdfjaでPDF化してみた - Qiita](http://qiita.com/hnakamur/items/8360a481a3820f374e3d)