SphinxドキュメントをビルドしてPDFファイルを出力する
こんにちは。サービスグループの武田です。
Sphinxで作成したドキュメントは、さまざまな形式にビルドできます。HTML形式でビルドすることが多そうですが、今回はPDF形式でビルドする方法を調べてみました。
環境
今回は次のような環境で検証しています。
$ sw_vers ProductName: Mac OS X ProductVersion: 10.15.5 BuildVersion: 19F101 $ pipenv --version pipenv, version 2018.11.26 $ brew --version Homebrew 2.4.0 Homebrew/homebrew-core (git revision 34bfab; last commit 2020-06-14) Homebrew/homebrew-cask (git revision c7734; last commit 2020-06-14) $ docker --version Docker version 19.03.8, build afacb8b
またsphinx-buildは3.1.1です。
PDFを出力するための準備
SphinxドキュメントをPDFとしてビルドするためには大きく次の2つの方法があります。
- MacTeXをインストールする
- TeX LiveがインストールされたDockerイメージを使用する
手軽なのは2で、公式のDockerイメージがDocker Hubで公開されています。Dockerがインストールされたマシンであればすぐに試せるでしょう。注意点として、提供されているイメージでは不足しているパッケージがある場合、自前でDockerfileを作成するなど準備が必要です。そういった環境を準備するのが面倒な場合やほかにもLaTeXを使うような場合は、マシンに環境を作ってしまうのが手っ取り早いです。
Dockerのインストールは割愛するとして、MacTeXのインストール手順をここで紹介します。MacTeXはTeXのディストリビューションであるTeX LiveをベースにしたmacOS用のディストリビューションです。MacTeXのインストール方法はいくつか用意されていますが、Homebrewを利用するのが簡単です。またGUIアプリケーションの有無でパッケージが異なります。今回は容量が軽いGUIなし版をインストールします。
$ brew cask install mactex-no-gui $ sudo tlmgr update --self --all $ sudo tlmgr paper a4
環境による差異もあるはずですが、数時間かかることもあります。気長にインストールが終わるのを待ちましょう。
PDF形式でビルドする（MacTeX）
まずは適当なSphinxプロジェクトを作成します。Sphinxのインストール先として、今回はグローバルではなくPipenvを利用します。
$ cd /path/to/working $ mkdir sphinx-test-doc && $_ $ pipenv --python 3.7 $ pipenv install sphinx $ pipenv run sphinx-quickstart --sep -p 'Sphinx Test Doc' -a 'Classmethod' -r '' -l ja
ビルドは2種類あり、latexターゲットでLaTeXのソースにビルドしてからあらためてmakeでPDFにビルドする方法。もうひとつがlatexpdfでPDFまで一気にビルドする方法です。特段理由がなければlatexpdfを指定するのが簡単です。
次のコマンドでビルドできます。
$ pipenv run make latexpdf
ビルドディレクトリに出力されています。
$ open build/latex/sphinxtestdoc.pdf
PDF形式でビルドする（Docker）
続いてDockerを利用する方法です。公式のDockerイメージは次の2つが用意されています。
sphinxdoc/sphinxがSphinxのパッケージのみがインストールされているイメージです。sphinxdoc/sphinx-latexpdfはTeX Liveがインストールされていますが、そのぶんサイズが大きくなっています。ちなみに最初に実行したsphinx-quickstartですが、これらのイメージを利用すればローカルに環境を作ることなくプロジェクトを作成できます。それでは後者を使ってビルドしてみましょう（念のため環境をきれいにしています）。
$ pipenv run make clean $ docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx-latexpdf
出力先は先ほどと同じです。
$ open build/latex/sphinxtestdoc.pdf
まとめ
Sphinxのメリットとしてさまざまな形式にビルドできることが挙げられます。その中でもおそらくニーズの多いPDF形式について調べてみました。どなたかのお役に立てば幸いです。
