torutkのブログ

ソフトウェア・エンジニアのブログ

Sphinxでドキュメント生成-PDF（Windowsでの始め方）

コンピュータ

昨日の日記の続きです。

今日は、SphinxでPDF形式のドキュメント生成を行います。PDF形式に出力するには、TeX経由で行う方法とSphinxのrst2pdf拡張で行う方法があるようです。

上記ドキュメントの比較によると、rst2pdfがよさそうなので、これを使ってPDF出力の仕組みをWindowsに整えます。なお、昨日同様、インターネットに接続していないPCでも環境を整えられるよう、必要なものをダウンロードしインストールします。

Windows上でrst2pdfを用意する

PythonのReportLab Toolkitモジュール

rst2pdfが依存するモジュール ReportLab Toolkit をインストールします。

実行するとPythonのディレクトリにモジュールが追加されます。

PythonのPython Image Library(PIL)モジュール

rst2pdfが依存するモジュール PIL をインストールします。

（5/21追記）本家PILのWindowsバイナリ版は、VC++2008デバッグビルドのDLLを（誤って）含めてしまい、利用者のPCにVC++2008がないとエラー（ImportError("The _imagingft C module is not installed")）になります。

そこで、有志がビルドしたWindows版PILを以下から入手しインストールします。

実行するとPythonのディレクトリにモジュールが追加されます。

本家サイト公開。1.1.7のWin用バイナリは問題があるので使用しない。

rst2pdfモジュール

rst2pdfをインストールします。

実行するとPythonのディレクトリにモジュールが追加されます。

rst2pdfの単体確認

まず、rst2pdf単体で、rst形式テキストをPDFに変換します。

C:\Users\torutk\Documents\work\hello> rst2pdf index.rst
  :（略）
C:\Users\torutk\Documents\work\hello>

PDFが生成されればOKです。

日本語フォント設定

rst2pdfはデフォルトのままだとフォント設定が欧文なので、日本語が文字化けします。そこで、rst2pdfに日本語フォント設定を記述したカスタムスタイルシート(ファイル名：ja.json)を指定します。

{
  "fontsAlias" : {
     "stdFont": "meiryo",
     "stdBold": "meiryob",
     "stdItalic": "meiryo",
     "stdBoldItalic": "meiryo",
     "stdMono": "MS Gothic",
     "stdMonoBold": "MS Gothic",
     "stdMonoItalic": "MS Gothic",
     "stdMonoBoldItalic": "MS Gothic"
},
"styles" : [
  ["base", {
   "wordWrap": "CJK"
  }],
  ["literal", {
   "wordWrap": "None"
  }]
 ]
}
  • 埋め込みフォントについて

rst2pdfの日本語化について、Web上のいくつかの記事においては、埋め込みフォントの設定をja.jsonに記述しています。埋め込みフォントの指定の必要性についてはよく分かっていないので、後日の課題としておきます。

  • stdMonoXXXの指定

はじめ、stdMonoの指定だけ記述していたところ、ソースコードブロックの中でコメント部分の日本語が化けてしまいました。いろいろ探してみたところ、rst2pdfで表のヘッダーの日本語が化けており、stdMonoItalicを指定して回避したとの記述を見つけました。これは！と思って試してみたところ、ソースコードブロックのコメント部分の日本語がでるようになりました。

PDF変換の実行

rst2pdfに、このスタイルシートとフォントのあるディレクトリを指定しPDFに変換します。

C:\Users\torutk\Documents\work\hello> rst2pdf -s ja --font-path=C:\Windows\Fonts index.rst
  :（略）
C:\Users\torutk\Documents\work\hello>

Sphinxからrst2pdf拡張でPDFを生成する

conf.pyにrst2pdf拡張の設定を追記

ドキュメント・ディレクトリにあるconf.pyに、PDF出力設定を追記します。以下に変更・追加行を示します。

extensions = ['sphinx.ext.autodoc', 'rst2pdf.pdfbuilder']

pdf_documents = [
    ('index', u'MyProject', u'My Project', u'Author Name'),
    ]
pdf_stylesheets = ['sphinx', 'kerning', 'a4', 'ja']
pdf_font_path = ['C:\Windows\Fonts']
pdf_language = "ja"
make.batにPDF生成コマンド追記

ドキュメント・ディレクトリにあるmake.batに、PDF生成コマンドを追記します。以下に追加行を示します。

if "%1" == "pdf" (
   %SPHINXBUILD% -b pdf %ALLSPHINXOPTS% %BUILDDIR%/pdf
   echo.
   echo.Build finished. The PDF files are in %BUILDDIR%/pdf
   goto end
)
ja.jsonをコピー

先にrst2pdfコマンド単体確認で使用したja.jsonファイルを、ドキュメント・ディレクトリにコピーします。

実行
C:\Users\torutk\Documents\work\hello> make pdf
   :（略）
C:\Users\torutk\Documents\work\hello>

_build\pdfディレクトリに、conf.py の pdf_documents = 行で2番目の要素で指定したファイル名のPDFが出力されます。