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

はじめに

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

サンプルプロジェクトのソースは
hnakamur/sphinx-rst2pdf-plantuml-japanese-example
に置きました。

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

動作環境はOSX 10.8.5です。

セットアップ

VLゴシックフォントをインストール

ダウンロードページからVLGothic-20130607.tar.bz2をダウンロードして展開し、
Finderで*.ttlファイルをOSXのFont Bookアプリにドラッグ＆ドロップします。
ファイルは~/Library/Fonts/にコピーされます。

Pythonをインストール

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

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でインストールしました。

brew install plantuml

fontconfigのインストール

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

brew install fontconfig

サンプルのセットアップ

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

一から行う場合

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

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ファイルの生成

make pdf

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

open _build/pdf/MyProject.pdf

参考にしたページ

• rst2pdf拡張を使ったPDFファイル作成 — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
• (6日目) Sphinx 拡張の紹介 - Hack like a rolling stone
• p.26 in Sphinx ではじめるドキュメント生活 2013 #sphinxconjp

ありがとうございます！

試行錯誤メモ

フォントの指定

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でインストールしました。

brew install fontconfig

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

(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の見た目に違いは無さそう気がしました。

@hnakamur2 フォントは何が使われているかとか埋め込まれているかとかは、ちょっと試した感じだと poppler の pdffonts コマンドで調べられそうでした。

— Kazuhiro NISHIYAMA (@znz) 2014, 5月 24

と教えてもらいました。ありがとうございます。

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