Sphinxから出力するPDFファイルにSVG画像を埋め込む

こんにちは。阿形です。

先日SphinxでLaTeX経由でPDFを出力できるように設定しました。

ところが困ったことに、Webで表示するのに都合がいいようにSVGで埋め込んでいた画像が原因で、エラーになってPDFが生成されません。
これはLaTeXの処理系がSVGに対応していないためです。
例えばPNGの画像を埋め込んだ場合は問題なくPDF出力が可能です。

さてどうしたものかと思い調べてみると、やはりいくつか方法があるようです。
ここでは比較的簡単に設定できるInkscapeとSphinx SVG to PDF Converter Extensionを使用した方法を取り上げてみます。

作業環境

こちらは前回と変わらずです。

• MacBook
• macOS High Sierra (10.13.6)
• Homebrew 2.0.4
  • Homebrew/homebrew-core (git revision a290; last commit 2019-03-16)
  • Homebrew/homebrew-cask (git revision 3db818; last commit 2019-03-17)
• Sphinx 1.8.0

Inkscapeのインストール

一応簡単に説明しておくと、Inkscapeは各種プラットフォームで動作する、ベクター画像を作成・編集するソフトウェアです。AdobeのIllustratorのようなものですね。

まずはInkscapeをインストールします。今回もHomebrewを使っていきます。以下のコマンドを実行します。

$ brew cask install xquartz
$ brew cask install inkscape

xquartzがインストールされていないとうまくインストールできないので、一緒にインストールしています。インストールが正常に進むと、最後に以下のようなメッセージが表示されます。

 ==> Linking Binary 'inkscape' to '/usr/local/bin/inkscape'.

ここの/usr/local/bin/inkscapeというパスは後で設定で使用するのでメモしておきます。

Sphinx SVG to PDF Converter Extensionのインストール

Sphinx SVG to PDF Converter Extensionは、Inkscapeまたはrsvg-convertコマンドのいずれかを使用してSVGをPDFに変換するSphinxのExtentsionです。

こちらはpipコマンドでインストールできます。

$ pip3 install sphinxcontrib-svg2pdfconverter

Sphinx SVG to PDF Converter Extensionの設定

Sphinx SVG to PDF Converter Extensionは、前述の通りInkscapeまたはrsvg-convertコマンドのいずれかを使用しますが、ここではInkscapeを使用する設定を説明します。

Sphinxのconf.pyファイルに以下の設定を追加します。

extensions = [ ‘sphinxcontrib.inkscapeconverter’]
inkscape_converter_bin = ‘/usr/local/bin/inkscape’

extensionsは他に必要なExtensionがある場合はカンマで区切って追加してください。

inkscape_converter_binに設定するパスは、先程Inkscapeのインストールの際に出力されたパスを記載します。Homebrewでインストールした場合は上記のパスのとおりになっているはずです。

使用方法

使用するに当たり特別な操作はありません。
Sphinxのドキュメントに*.svgの画像ファイルが埋め込まれている場合、自動的にInkscapeを使用してPDFファイルに変換され、そのPDFファイルがドキュメント全体のPDFファイルに埋め込まれます。

これでWebではSVG、PDFではPDFで画像が埋め込まれるので、ファイルサイズが小さくて済みますね。

ちょっとした欠点

勘のいい方はお気づきかと思いますが、Sphinxのビルド時に画像変換のためにInkscapeが起動するため、少し処理が遅く感じるかもしれません。特にmacOSの場合はXquartzを起動してからInkscapeを起動するので、ちょっともたついた感じになります。
ただ、画像ファイルの更新がなければ以前に変換したものがそのまま使用されるので、それほど問題ではないと思います。

今回何も考えずにInkscapeを使ってしまいましたが、rsvg-convertを使用したほうが処理は軽いかもしれませんので、気になる方はぜひ試してみてください。

以上です。